{"openapi":"3.1.0","info":{"title":"Alienmail API","version":"1.0","description":"Connect your own systems to Alienmail: list, start and pause campaigns, keep their leads in step with your CRM, and manage sending mailboxes. JSON over HTTPS."},"servers":[{"url":"https://app.alienmail.io/api/v1","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Campaigns","description":"List campaigns, start them and pause them."},{"name":"Leads","description":"The people a campaign emails: list, add, edit, stop and remove them."},{"name":"Mailboxes","description":"The mailboxes your workspace sends from."}],"paths":{"/campaigns":{"get":{"operationId":"listCampaigns","summary":"List campaigns","description":"The campaigns of your workspace, newest first. Archived campaigns are included; deleted ones are not.\n\nRequires the `CAMPAIGN_READ` permission.","tags":["Campaigns"],"parameters":[{"name":"status","in":"query","description":"Only campaigns with this status.","required":false,"schema":{"type":"string","enum":["draft","active","paused","completed","archived"]}},{"name":"search","in":"query","description":"Only campaigns whose name contains this text.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Items per page, 1 to 100. Default 25. A number outside that range is rounded to the nearest limit (`0` is 1, `500` is 100) and a fraction rounded down; anything that is not a number is the default.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page. Anything else returns 400.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of campaigns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/campaigns/{id}/start":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"integer","examples":[42]}}],"post":{"operationId":"startCampaign","summary":"Start or resume a campaign","description":"Starts a `draft` campaign, resumes a `paused` one, or restarts a `completed` one. Leads that were waiting become `active` and their next email is queued. A campaign that is already `active` is returned unchanged, so the call is safe to repeat.\n\nIt is refused with 409 when the campaign is `archived`, its end date has passed, none of its email steps has content, or it has no mailbox that is active and connected. `message` says which.\n\nRequires the `CAMPAIGN_START` permission.","tags":["Campaigns"],"responses":{"200":{"description":"The campaign, now `active`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/campaigns/{id}/pause":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"integer","examples":[42]}}],"post":{"operationId":"pauseCampaign","summary":"Pause a campaign","description":"Stops sending: emails that were waiting to go out are taken off the queue. Start the campaign again to resume; each lead then continues with their next email. A campaign that is already `paused` is returned unchanged.\n\nOnly an `active` campaign can be paused. Any other status returns 409.\n\nRequires the `CAMPAIGN_STATUS_UPDATE` permission.","tags":["Campaigns"],"responses":{"200":{"description":"The campaign, now `paused`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/campaigns/{id}/leads":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"integer","examples":[42]}}],"get":{"operationId":"listLeads","summary":"List leads","description":"The leads of a campaign, newest first. Leads that were removed from the campaign are not listed.\n\nRequires the `CAMPAIGN_READ` permission.","tags":["Leads"],"parameters":[{"name":"status","in":"query","description":"Only leads with this status.","required":false,"schema":{"type":"string","enum":["pending","active","stopped","completed","unsubscribed","bounced","skipped"]}},{"name":"search","in":"query","description":"Only leads whose email, first name, last name or company contains this text. Search for a full email address to look up one lead.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Items per page, 1 to 100. Default 25. A number outside that range is rounded to the nearest limit (`0` is 1, `500` is 100) and a fraction rounded down; anything that is not a number is the default.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page. Anything else returns 400.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of leads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"addLeads","summary":"Add leads","description":"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.\n\nThe call is safe to repeat: someone already in the campaign is counted in `alreadyIn` and only their custom values are updated. A person who is already a lead in your workspace keeps the fields stored there; change them with [Update a lead](/api-reference/leads/updateLead). People whose address bounced or who unsubscribed in your workspace are left out and counted.\n\nAn entry with an invalid email is reported in `invalid` and the others are still added, so check it. It is refused with 409 when the campaign is `archived`, or `completed` with no connected mailbox or a past end date.\n\nRequires the `LEAD_CAMPAIGN_ENROLL` permission.","tags":["Leads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadsAddBody"}}}},"responses":{"200":{"description":"What happened to the people in the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadsAddResult"}}}},"400":{"$ref":"#/components/responses/BadRequestBody"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"removeLeads","summary":"Remove leads","description":"Removes up to 500 leads from a campaign by email. Their waiting emails are cancelled. The emails the campaign already sent them stay in its statistics, and the people stay in your workspace's leads.\n\nEmails that are not leads of the campaign are counted in `notInCampaign`, so the call is safe to repeat. An `archived` campaign returns 409.\n\nRequires the `LEAD_CAMPAIGN_ENROLL` permission.","tags":["Leads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadsRemoveBody"}}}},"responses":{"200":{"description":"What happened to the emails in the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadsRemoveResult"}}}},"400":{"$ref":"#/components/responses/BadRequestBody"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/campaigns/{id}/leads/{email}":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"integer","examples":[42]}},{"name":"email","in":"path","required":true,"description":"The lead email address. Encode it for a URL (`@` as `%40`). Upper and lower case are treated the same.","schema":{"type":"string","examples":["ada@example.com"]}}],"patch":{"operationId":"updateLead","summary":"Update a lead","description":"Changes a lead's fields and custom values, and stops or resumes emails to them. Only what you send changes.\n\nFields 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.\n\n`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.\n\nRequires the `LEAD_CAMPAIGN_ENROLL` permission.","tags":["Leads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadPatchBody"}}}},"responses":{"200":{"description":"The updated lead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"400":{"$ref":"#/components/responses/BadRequestBody"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"removeLead","summary":"Remove a lead","description":"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.\n\nRequires the `LEAD_CAMPAIGN_ENROLL` permission.","tags":["Leads"],"responses":{"200":{"description":"The lead was removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadRemoved"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/mailboxes":{"get":{"operationId":"listMailboxes","summary":"List mailboxes","description":"The mailboxes connected to your workspace, newest first. Passwords, tokens and server settings are never returned.\n\nRequires the `SMTP_READ` permission.","tags":["Mailboxes"],"parameters":[{"name":"limit","in":"query","description":"Items per page, 1 to 100. Default 25. A number outside that range is rounded to the nearest limit (`0` is 1, `500` is 100) and a fraction rounded down; anything that is not a number is the default.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page. Anything else returns 400.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of mailboxes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/mailboxes/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The mailbox id, from the mailbox list.","schema":{"type":"integer","examples":[7]}}],"patch":{"operationId":"updateMailbox","summary":"Update a mailbox","description":"Changes a mailbox's sender name, its daily sending limit, or turns it off and on. Only what you send changes. Server settings, logins and passwords can't be changed through the API: reconnect the mailbox in Alienmail.\n\nRequires the `SMTP_UPDATE` permission.","tags":["Mailboxes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxPatchBody"}}}},"responses":{"200":{"description":"The updated mailbox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"}}}},"400":{"$ref":"#/components/responses/BadRequestBody"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key of your workspace, from Workspace settings, Integrations. Each key has a role, and the role decides which endpoints it may call."}},"schemas":{"LeadInput":{"type":"object","properties":{"email":{"type":"string","description":"Email address. Trimmed and lower-cased. An address that is not valid is reported in `invalid` and the rest of the call still runs.","examples":["ada@example.com"]},"firstName":{"description":"First name. Up to 191 characters.","examples":["Ada"],"type":"string","maxLength":191},"lastName":{"description":"Last name. Up to 191 characters.","examples":["Lovelace"],"type":"string","maxLength":191},"salutation":{"description":"How to address them, like `Dr.` or `Ms.`. Up to 191 characters.","examples":["Ms."],"type":"string","maxLength":191},"jobTitle":{"description":"Job title. Up to 191 characters.","examples":["Head of Engineering"],"type":"string","maxLength":191},"department":{"description":"Department. Up to 191 characters.","examples":["Engineering"],"type":"string","maxLength":191},"seniority":{"description":"Seniority level. Up to 191 characters.","examples":["Director"],"type":"string","maxLength":191},"phone":{"description":"Phone number, in any format. Up to 191 characters.","examples":["+44 20 7946 0958"],"type":"string","maxLength":191},"linkedinUrl":{"description":"LinkedIn profile URL. Up to 191 characters.","examples":["https://www.linkedin.com/in/ada-lovelace"],"type":"string","maxLength":191},"gender":{"description":"Gender. Up to 191 characters.","examples":["female"],"type":"string","maxLength":191},"timezone":{"description":"Time zone. Up to 191 characters.","examples":["Europe/London"],"type":"string","maxLength":191},"language":{"description":"Language. Up to 191 characters.","examples":["en"],"type":"string","maxLength":191},"company":{"description":"Company name. Up to 191 characters.","examples":["Analytical Engines"],"type":"string","maxLength":191},"companyDomain":{"description":"Company website domain. Up to 191 characters.","examples":["analyticalengines.com"],"type":"string","maxLength":191},"industry":{"description":"Industry. Up to 191 characters.","examples":["Software"],"type":"string","maxLength":191},"companySize":{"description":"Company size, as text. Up to 191 characters.","examples":["51-200"],"type":"string","maxLength":191},"revenue":{"description":"Company revenue, as text. Up to 191 characters.","examples":["$10M-$50M"],"type":"string","maxLength":191},"linkedinCompanyUrl":{"description":"LinkedIn company page URL. Up to 191 characters.","examples":["https://www.linkedin.com/company/analytical-engines"],"type":"string","maxLength":191},"city":{"description":"City. Up to 191 characters.","examples":["London"],"type":"string","maxLength":191},"state":{"description":"State or region. Up to 191 characters.","examples":["England"],"type":"string","maxLength":191},"country":{"description":"Country. Up to 191 characters.","examples":["United Kingdom"],"type":"string","maxLength":191},"countryCode":{"description":"Country code. Up to 191 characters.","examples":["GB"],"type":"string","maxLength":191},"description":{"description":"Notes about this person. Up to 5000 characters; only your workspace sees them.","examples":["Met at the Manchester meetup."],"type":"string","maxLength":5000},"custom":{"description":"Custom values for this campaign, usable in emails as `{{key}}`. A key that is not yet a custom column of the campaign is added as one when it is made of lower-case letters, digits and underscores, starts with a letter, is at most 40 characters and is not a built-in variable such as `first_name`; other keys are returned in `ignoredCustomKeys`. A campaign holds up to 50 custom columns.","examples":[{"plan":"pro","renewal_date":"2027-01-04"}],"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":5000},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}},"required":["email"],"additionalProperties":false,"description":"A person to add to the campaign."},"LeadsAddBody":{"type":"object","properties":{"leads":{"minItems":1,"maxItems":500,"type":"array","items":{"$ref":"#/components/schemas/LeadInput"},"description":"1 to 500 people. When an email appears twice, the first entry is used."}},"required":["leads"],"additionalProperties":false},"LeadsRemoveBody":{"type":"object","properties":{"emails":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string"},"description":"1 to 500 email addresses to remove from the campaign.","examples":[["ada@example.com","grace@example.com"]]}},"required":["emails"],"additionalProperties":false},"LeadPatchBody":{"type":"object","properties":{"firstName":{"description":"First name. Up to 191 characters. `null` or an empty string clears it.","examples":["Ada"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"lastName":{"description":"Last name. Up to 191 characters. `null` or an empty string clears it.","examples":["Lovelace"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"salutation":{"description":"How to address them, like `Dr.` or `Ms.`. Up to 191 characters. `null` or an empty string clears it.","examples":["Ms."],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"jobTitle":{"description":"Job title. Up to 191 characters. `null` or an empty string clears it.","examples":["Head of Engineering"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"department":{"description":"Department. Up to 191 characters. `null` or an empty string clears it.","examples":["Engineering"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"seniority":{"description":"Seniority level. Up to 191 characters. `null` or an empty string clears it.","examples":["Director"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"phone":{"description":"Phone number, in any format. Up to 191 characters. `null` or an empty string clears it.","examples":["+44 20 7946 0958"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"linkedinUrl":{"description":"LinkedIn profile URL. Up to 191 characters. `null` or an empty string clears it.","examples":["https://www.linkedin.com/in/ada-lovelace"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"gender":{"description":"Gender. Up to 191 characters. `null` or an empty string clears it.","examples":["female"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"timezone":{"description":"Time zone. Up to 191 characters. `null` or an empty string clears it.","examples":["Europe/London"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"language":{"description":"Language. Up to 191 characters. `null` or an empty string clears it.","examples":["en"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"company":{"description":"Company name. Up to 191 characters. `null` or an empty string clears it.","examples":["Analytical Engines"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"companyDomain":{"description":"Company website domain. Up to 191 characters. `null` or an empty string clears it.","examples":["analyticalengines.com"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"industry":{"description":"Industry. Up to 191 characters. `null` or an empty string clears it.","examples":["Software"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"companySize":{"description":"Company size, as text. Up to 191 characters. `null` or an empty string clears it.","examples":["51-200"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"revenue":{"description":"Company revenue, as text. Up to 191 characters. `null` or an empty string clears it.","examples":["$10M-$50M"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"linkedinCompanyUrl":{"description":"LinkedIn company page URL. Up to 191 characters. `null` or an empty string clears it.","examples":["https://www.linkedin.com/company/analytical-engines"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"city":{"description":"City. Up to 191 characters. `null` or an empty string clears it.","examples":["London"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"state":{"description":"State or region. Up to 191 characters. `null` or an empty string clears it.","examples":["England"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"country":{"description":"Country. Up to 191 characters. `null` or an empty string clears it.","examples":["United Kingdom"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"countryCode":{"description":"Country code. Up to 191 characters. `null` or an empty string clears it.","examples":["GB"],"anyOf":[{"type":"string","maxLength":191},{"type":"null"}]},"description":{"description":"Notes about this person. Up to 5000 characters; only your workspace sees them. `null` or an empty string clears it.","examples":["Met at the Manchester meetup."],"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom":{"description":"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.","examples":[{"plan":"enterprise"}],"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":5000},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"status":{"description":"`stopped` stops emails to this lead; they stay in the campaign. `active` resumes a stopped lead.","examples":["stopped"],"type":"string","enum":["active","stopped"]}},"additionalProperties":false},"MailboxPatchBody":{"type":"object","properties":{"name":{"description":"The sender name recipients see.","examples":["Ada from Analytical Engines"],"type":"string","minLength":1,"maxLength":191},"dailyLimit":{"description":"Most emails this mailbox sends per day, 1 to 2000.","examples":[50],"type":"integer","minimum":1,"maximum":2000},"active":{"description":"`false` stops sending from this mailbox; `true` turns it back on.","examples":[true],"type":"boolean"}},"additionalProperties":false},"Campaign":{"type":"object","properties":{"id":{"type":"integer","description":"The campaign id, as in the campaign URL in Alienmail.","examples":[42]},"name":{"type":"string","examples":["Q1 outreach"]},"status":{"type":"string","enum":["draft","active","paused","completed","archived"],"examples":["active"]},"leadCount":{"type":"integer","description":"Leads in the campaign. Removed leads are not counted.","examples":[180]},"sentCount":{"type":"integer","description":"Emails the campaign has sent, bounced ones included.","examples":[412]},"lastSentAt":{"anyOf":[{"type":"string","format":"date-time","description":"When the campaign last sent an email.","examples":["2026-11-13T09:30:00.000Z"]},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","examples":["2026-11-13T09:30:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-11-13T09:30:00.000Z"]}},"required":["id","name","status","leadCount","sentCount","lastSentAt","createdAt","updatedAt"],"additionalProperties":false},"CampaignList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"nextCursor":{"description":"Pass as `cursor` to get the next page. `null` on the last page.","examples":[null],"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false},"Lead":{"type":"object","properties":{"email":{"type":"string","description":"The lead email address, lower case. It identifies the lead in the API.","examples":["ada@example.com"]},"status":{"type":"string","enum":["pending","active","stopped","completed","unsubscribed","bounced","skipped"],"description":"`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.","examples":["active"]},"firstName":{"description":"First name.","examples":["Ada"],"type":["string","null"]},"lastName":{"description":"Last name.","examples":["Lovelace"],"type":["string","null"]},"salutation":{"description":"How to address them, like `Dr.` or `Ms.`.","examples":["Ms."],"type":["string","null"]},"jobTitle":{"description":"Job title.","examples":["Head of Engineering"],"type":["string","null"]},"department":{"description":"Department.","examples":["Engineering"],"type":["string","null"]},"seniority":{"description":"Seniority level.","examples":["Director"],"type":["string","null"]},"phone":{"description":"Phone number, in any format.","examples":["+44 20 7946 0958"],"type":["string","null"]},"linkedinUrl":{"description":"LinkedIn profile URL.","examples":["https://www.linkedin.com/in/ada-lovelace"],"type":["string","null"]},"gender":{"description":"Gender.","examples":["female"],"type":["string","null"]},"timezone":{"description":"Time zone.","examples":["Europe/London"],"type":["string","null"]},"language":{"description":"Language.","examples":["en"],"type":["string","null"]},"company":{"description":"Company name.","examples":["Analytical Engines"],"type":["string","null"]},"companyDomain":{"description":"Company website domain.","examples":["analyticalengines.com"],"type":["string","null"]},"industry":{"description":"Industry.","examples":["Software"],"type":["string","null"]},"companySize":{"description":"Company size, as text.","examples":["51-200"],"type":["string","null"]},"revenue":{"description":"Company revenue, as text.","examples":["$10M-$50M"],"type":["string","null"]},"linkedinCompanyUrl":{"description":"LinkedIn company page URL.","examples":["https://www.linkedin.com/company/analytical-engines"],"type":["string","null"]},"city":{"description":"City.","examples":["London"],"type":["string","null"]},"state":{"description":"State or region.","examples":["England"],"type":["string","null"]},"country":{"description":"Country.","examples":["United Kingdom"],"type":["string","null"]},"countryCode":{"description":"Country code.","examples":["GB"],"type":["string","null"]},"description":{"description":"Notes about this person.","examples":["Met at the Manchester meetup."],"type":["string","null"]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"The custom values of this lead in this campaign, as text.","examples":[{"plan":"pro","renewal_date":"2027-01-04"}]},"lastSentAt":{"anyOf":[{"type":"string","format":"date-time","description":"When the campaign last emailed this lead.","examples":["2026-11-13T09:30:00.000Z"]},{"type":"null"}]},"addedAt":{"type":"string","format":"date-time","description":"When the lead was added to the campaign.","examples":["2026-11-13T09:30:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-11-13T09:30:00.000Z"]}},"required":["email","status","firstName","lastName","salutation","jobTitle","department","seniority","phone","linkedinUrl","gender","timezone","language","company","companyDomain","industry","companySize","revenue","linkedinCompanyUrl","city","state","country","countryCode","description","custom","lastSentAt","addedAt","updatedAt"],"additionalProperties":false},"LeadList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"nextCursor":{"description":"Pass as `cursor` to get the next page. `null` on the last page.","examples":[null],"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false},"LeadsAddResult":{"type":"object","properties":{"received":{"type":"integer","description":"Entries in the request.","examples":[2]},"added":{"type":"integer","description":"People who are now new leads of the campaign.","examples":[2]},"reactivated":{"type":"integer","description":"People who were removed from the campaign earlier and are back in it.","examples":[0]},"alreadyIn":{"type":"integer","description":"People who were already in the campaign. Only their custom values were updated.","examples":[0]},"skippedBounced":{"type":"integer","description":"People left out because their address bounced in your workspace.","examples":[0]},"skippedUnsubscribed":{"type":"integer","description":"People left out because they unsubscribed in your workspace.","examples":[0]},"invalid":{"type":"array","items":{"type":"object","properties":{"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Position of the entry in the request, from 0.","examples":[3]},"email":{"type":"string","examples":["not-an-email"]},"reason":{"type":"string","examples":["Missing or invalid email."]}},"required":["index","email","reason"],"additionalProperties":false},"description":"Entries that could not be added, with the reason.","examples":[[]]},"ignoredCustomKeys":{"type":"array","items":{"type":"string"},"description":"Custom keys that could not become a custom column.","examples":[[]]}},"required":["received","added","reactivated","alreadyIn","skippedBounced","skippedUnsubscribed","invalid","ignoredCustomKeys"],"additionalProperties":false},"LeadsRemoveResult":{"type":"object","properties":{"received":{"type":"integer","description":"Emails in the request.","examples":[2]},"removed":{"type":"integer","description":"Leads removed from the campaign.","examples":[1]},"notInCampaign":{"type":"integer","description":"Emails that were not leads of the campaign.","examples":[1]},"invalid":{"type":"array","items":{"type":"object","properties":{"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Position of the entry in the request, from 0.","examples":[3]},"email":{"type":"string","examples":["not-an-email"]},"reason":{"type":"string","examples":["Missing or invalid email."]}},"required":["index","email","reason"],"additionalProperties":false},"description":"Entries that are not email addresses.","examples":[[]]}},"required":["received","removed","notInCampaign","invalid"],"additionalProperties":false},"LeadRemoved":{"type":"object","properties":{"removed":{"type":"boolean","const":true}},"required":["removed"],"additionalProperties":false},"Mailbox":{"type":"object","properties":{"id":{"type":"integer","description":"The mailbox id.","examples":[7]},"email":{"type":"string","description":"The address it sends from.","examples":["ada@analyticalengines.com"]},"name":{"type":"string","description":"The sender name recipients see.","examples":["Ada from Analytical Engines"]},"provider":{"type":"string","enum":["smtp","google","microsoft","outlook"],"description":"How the mailbox is connected.","examples":["google"]},"active":{"type":"boolean","description":"Whether campaigns may send from it."},"connected":{"type":"boolean","description":"`false` when the last connection check failed. Reconnect it in Alienmail."},"rateLimited":{"type":"boolean","description":"The mail provider is throttling this mailbox.","examples":[false]},"dailyLimit":{"type":"integer","description":"Most emails it sends per day, 1 to 2000.","examples":[50]},"sentToday":{"type":"integer","description":"Emails counted against the daily limit so far.","examples":[12]},"createdAt":{"type":"string","format":"date-time","examples":["2026-11-13T09:30:00.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-11-13T09:30:00.000Z"]}},"required":["id","email","name","provider","active","connected","rateLimited","dailyLimit","sentToday","createdAt","updatedAt"],"additionalProperties":false},"MailboxList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Mailbox"}},"nextCursor":{"description":"Pass as `cursor` to get the next page. `null` on the last page.","examples":[null],"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request","invalid_json","unauthorized","forbidden","not_found","method_not_allowed","conflict","unsupported_media_type","rate_limited","server_error"]},"message":{"type":"string","examples":["The request is invalid. Check the fields."]},"fields":{"description":"Field name to problem, for validation errors.","examples":[{"dailyLimit":"Too big: expected number to be <=2000"}],"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid: `fields` names the parameters to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequestBody":{"description":"The request is invalid: `fields` names the fields to fix. Code `invalid_json` when the body is not valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key's role lacks the permission this endpoint needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The campaign, lead or mailbox was not found in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"The campaign, lead or mailbox is in a state that does not allow this. `message` says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnsupportedMediaType":{"description":"The body is not JSON: send it with `Content-Type: application/json`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}}