Update a lead
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.
apiKeyAuthorizationBearer <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.
id*integerThe 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*stringThe lead email address. Encode it for a URL (@ as %40). Upper and lower case are treated the same.
application/json- 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?stringstopped stops emails to this lead; they stay in the campaign. active resumes a stopped lead.
"active""stopped"The updated lead.
application/json- response
email*stringThe lead email address, lower case. It identifies the lead in the API.
status*stringpending: 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.
"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*|nulladdedAt*stringWhen the lead was added to the campaign.
date-timeupdatedAt*stringdate-timecurl -X PATCH 'https://app.alienmail.io/api/v1/campaigns/42/leads/ada@example.com' \ -H 'Content-Type: application/json' \ -d '{}'{ "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"}Add leads POST
Adds up to 500 people to a campaign by email. In an `active` campaign a new lead's first email is queued at once; in a `draft` or `paused` one they wait as `pending` until it starts. Adding to a `completed` campaign makes it `active` again.
Remove a lead DELETE
Removes one lead from a campaign and cancels their waiting emails. The emails the campaign already sent them stay in its statistics, and the person stays in your workspace's leads. An `archived` campaign returns 409.