Skip to Content
Alienmail Docs
Leads

Update a lead

PATCH
/campaigns/{id}/leads/{email}

Changes a lead's fields and custom values, and stops or resumes emails to them. Only what you send changes.

Fields and custom values can be edited while the campaign is draft or paused, and in an active campaign until the lead has been sent an email. Otherwise the call returns 409: pause the campaign first.

status: "stopped" stops emails to an active or pending lead; they stay in the campaign. status: "active" resumes a stopped lead with their next email. Other changes of status return 409, as does any status change in an archived campaign.

Requires the LEAD_CAMPAIGN_ENROLL permission.

Authorization

apiKey
headerAuthorizationBearer <token>

An API key of your workspace, from Workspace settings, Integrations. Each key has a role, and the role decides which endpoints it may call.

Path Parameters

id*integer

The campaign id: the number in the campaign URL in Alienmail, or id from the campaign list. An id that is not a campaign of your workspace returns 404.

email*string

The lead email address. Encode it for a URL (@ as %40). Upper and lower case are treated the same.

Request Body

application/json
  1. body
firstName?|

First name. Up to 191 characters. null or an empty string clears it.

lastName?|

Last name. Up to 191 characters. null or an empty string clears it.

salutation?|

How to address them, like Dr. or Ms.. Up to 191 characters. null or an empty string clears it.

jobTitle?|

Job title. Up to 191 characters. null or an empty string clears it.

department?|

Department. Up to 191 characters. null or an empty string clears it.

seniority?|

Seniority level. Up to 191 characters. null or an empty string clears it.

phone?|

Phone number, in any format. Up to 191 characters. null or an empty string clears it.

linkedinUrl?|

LinkedIn profile URL. Up to 191 characters. null or an empty string clears it.

gender?|

Gender. Up to 191 characters. null or an empty string clears it.

timezone?|

Time zone. Up to 191 characters. null or an empty string clears it.

language?|

Language. Up to 191 characters. null or an empty string clears it.

company?|

Company name. Up to 191 characters. null or an empty string clears it.

companyDomain?|

Company website domain. Up to 191 characters. null or an empty string clears it.

industry?|

Industry. Up to 191 characters. null or an empty string clears it.

companySize?|

Company size, as text. Up to 191 characters. null or an empty string clears it.

revenue?|

Company revenue, as text. Up to 191 characters. null or an empty string clears it.

linkedinCompanyUrl?|

LinkedIn company page URL. Up to 191 characters. null or an empty string clears it.

city?|

City. Up to 191 characters. null or an empty string clears it.

state?|

State or region. Up to 191 characters. null or an empty string clears it.

country?|

Country. Up to 191 characters. null or an empty string clears it.

countryCode?|

Country code. Up to 191 characters. null or an empty string clears it.

description?|

Notes about this person. Up to 5000 characters; only your workspace sees them. null or an empty string clears it.

custom?

Custom values to change. Each key must already be a custom column of the campaign. null or an empty string clears a value; keys you leave out are kept.

status?string

stopped stops emails to this lead; they stay in the campaign. active resumes a stopped lead.

Value in"active""stopped"

Response Body

The updated lead.

application/json
  1. response
email*string

The lead email address, lower case. It identifies the lead in the API.

status*string

pending: waiting for the campaign to start. active: getting emails. stopped: emails stopped by you or because they replied; still in the campaign. completed: finished the sequence. unsubscribed and bounced: no more emails. skipped: not emailed because the campaign skips leads that failed the email check; goes back to active when the campaign stops skipping them or a new check passes.

Value in"pending""active""stopped""completed""unsubscribed""bounced""skipped"
firstName*|

First name.

lastName*|

Last name.

salutation*|

How to address them, like Dr. or Ms..

jobTitle*|

Job title.

department*|

Department.

seniority*|

Seniority level.

phone*|

Phone number, in any format.

linkedinUrl*|

LinkedIn profile URL.

gender*|

Gender.

timezone*|

Time zone.

language*|

Language.

company*|

Company name.

companyDomain*|

Company website domain.

industry*|

Industry.

companySize*|

Company size, as text.

revenue*|

Company revenue, as text.

linkedinCompanyUrl*|

LinkedIn company page URL.

city*|

City.

state*|

State or region.

country*|

Country.

countryCode*|

Country code.

description*|

Notes about this person.

custom*

The custom values of this lead in this campaign, as text.

lastSentAt*|null
addedAt*string

When the lead was added to the campaign.

Formatdate-time
updatedAt*string
Formatdate-time
Example Request
curl -X PATCH 'https://app.alienmail.io/api/v1/campaigns/42/leads/ada@example.com' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "email": "ada@example.com",  "status": "active",  "firstName": "Ada",  "lastName": "Lovelace",  "salutation": "Ms.",  "jobTitle": "Head of Engineering",  "department": "Engineering",  "seniority": "Director",  "phone": "+44 20 7946 0958",  "linkedinUrl": "https://www.linkedin.com/in/ada-lovelace",  "gender": "female",  "timezone": "Europe/London",  "language": "en",  "company": "Analytical Engines",  "companyDomain": "analyticalengines.com",  "industry": "Software",  "companySize": "51-200",  "revenue": "$10M-$50M",  "linkedinCompanyUrl": "https://www.linkedin.com/company/analytical-engines",  "city": "London",  "state": "England",  "country": "United Kingdom",  "countryCode": "GB",  "description": "Met at the Manchester meetup.",  "custom": {    "plan": "pro",    "renewal_date": "2027-01-04"  },  "lastSentAt": "2026-11-13T09:30:00.000Z",  "addedAt": "2026-11-13T09:30:00.000Z",  "updatedAt": "2026-11-13T09:30:00.000Z"}