# AI tools and MCP (/ai-tools) These docs are built to be read by AI tools as well as people, so an assistant can write your Alienmail integration with the real endpoints and rules. ## Copy page and open in AI apps [#copy-page-and-open-in-ai-apps] Every page has a **Copy page** button at the top. Its menu has: - **Copy page**: the page as Markdown, ready to paste into a chat. - **View as Markdown**: the plain-text version of the page. - **Open in ChatGPT** and **Open in Claude**: start a chat that reads the page. - **llms.txt**: the index of the whole site for language models. ## Markdown and llms.txt [#markdown-and-llmstxt] | URL | What it is | |---|---| | [`/llms.txt`](/llms.txt) | An index of every page with a short description, in the [llms.txt](https://llmstxt.org) format. | | [`/llms-full.txt`](/llms-full.txt) | All pages in one Markdown file, including every endpoint of the API reference. | | `/.md` | One page as Markdown, like [`/quickstart.md`](/quickstart.md). | | [`/openapi.json`](/openapi.json) | The OpenAPI 3.1 spec of the API. | Pages also answer with Markdown when a tool asks for it with `Accept: text/markdown`. ## Docs MCP server [#docs-mcp-server] The docs have a [Model Context Protocol](https://modelcontextprotocol.io) server, so AI coding tools can search and read them while they work. It is public and read-only, and needs no sign-in. ```txt https://docs.alienmail.io/api/mcp ``` It has three tools: | Tool | What it does | |---|---| | `search` | Searches the docs. | | `list_pages` | Lists every page with its URL. | | `get_page` | Returns a page as Markdown. | ### Connect your tool [#connect-your-tool] ```bash claude mcp add --transport http alienmail-docs https://docs.alienmail.io/api/mcp ``` Add to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project: ```json { "mcpServers": { "alienmail-docs": { "url": "https://docs.alienmail.io/api/mcp" } } } ``` Add to `.vscode/mcp.json`: ```json { "servers": { "alienmail-docs": { "type": "http", "url": "https://docs.alienmail.io/api/mcp" } } } ``` In Claude, open **Settings → Connectors**, choose **Add custom connector**, and enter `https://docs.alienmail.io/api/mcp`. Any client that supports remote MCP servers over Streamable HTTP can use `https://docs.alienmail.io/api/mcp`. Then ask, for example: _"Using the Alienmail docs, write a function that adds our new trial users to an Alienmail campaign."_ The docs MCP server reads documentation only. It can't see or change your Alienmail data. To let an AI tool work with your account, connect the [Alienmail MCP server](/guides/mcp-server): sign in from the AI tool, or use an [API key](/authentication). # Overview (/api-reference) The reference is generated from the same schemas the API validates requests with, so it always matches what the API accepts. ## Base URL [#base-url] ```txt https://app.alienmail.io/api/v1 ``` Send your API key on every request as `Authorization: Bearer `. See [Authentication](/authentication). ## Try it [#try-it] Each endpoint page has a playground. Enter your API key in **Authorization**, fill in the parameters and body, and press **Send** to call the live API and see the response. Requests go through this site to the API, and your key is not stored. Requests from the playground are real. Starting a campaign sends email, and adding, updating and removing leads change your data. ## Endpoints [#endpoints] | Method | Path | Permission | |---|---|---| | `GET` | [`/campaigns`](/api-reference/campaigns/listCampaigns) | `CAMPAIGN_READ` | | `POST` | [`/campaigns/{id}/start`](/api-reference/campaigns/startCampaign) | `CAMPAIGN_START` | | `POST` | [`/campaigns/{id}/pause`](/api-reference/campaigns/pauseCampaign) | `CAMPAIGN_STATUS_UPDATE` | | `GET` | [`/campaigns/{id}/leads`](/api-reference/leads/listLeads) | `CAMPAIGN_READ` | | `POST` | [`/campaigns/{id}/leads`](/api-reference/leads/addLeads) | `LEAD_CAMPAIGN_ENROLL` | | `PATCH` | [`/campaigns/{id}/leads/{email}`](/api-reference/leads/updateLead) | `LEAD_CAMPAIGN_ENROLL` | | `DELETE` | [`/campaigns/{id}/leads/{email}`](/api-reference/leads/removeLead) | `LEAD_CAMPAIGN_ENROLL` | | `DELETE` | [`/campaigns/{id}/leads`](/api-reference/leads/removeLeads) | `LEAD_CAMPAIGN_ENROLL` | | `GET` | [`/mailboxes`](/api-reference/mailboxes/listMailboxes) | `SMTP_READ` | | `PATCH` | [`/mailboxes/{id}`](/api-reference/mailboxes/updateMailbox) | `SMTP_UPDATE` | ## Download the spec [#download-the-spec] [`/openapi.json`](/openapi.json) is the OpenAPI 3.1 spec. Import it into Postman or Insomnia, or generate a typed client with a tool like `openapi-typescript`. # Authentication (/authentication) Every request needs an API key, sent as a Bearer token in the `Authorization` header: ```bash curl "https://app.alienmail.io/api/v1/campaigns" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" ``` There is no sign-in step and no token to refresh: send the key itself on each request. ## API keys [#api-keys] Create keys in **Workspace settings → Integrations**, under **API keys**. Each key has: - **A name**, so you know which system uses it. Names are unique in a workspace. - **A role**, which decides what the key may do. The full key is shown once, when it is created. Alienmail keeps only a hash, so a lost key can't be shown again: create a new one and delete the old one. The key list shows when each key was last used. A workspace can create up to 10 keys a day. A key belongs to **one workspace**. It only sees and changes that workspace's campaigns, leads and mailboxes, which is why API paths have no workspace id. To work with several workspaces, create a key in each. A key acts for your workspace. Store it in your server's secrets, never in browser or mobile code, and delete it right away if it leaks. ## Roles and permissions [#roles-and-permissions] When you create a key you pick its role: | Role | What the key can do | |---|---| | **Read-Only API Key** | Read: list campaigns, leads and mailboxes. | | **Write Access Key** | Everything in this API: read, start and pause campaigns, add, update and remove leads, update mailboxes. | A role is a set of permissions, and each endpoint needs one of them. A request to an endpoint whose permission the role lacks gets `403 forbidden`, and the message names the missing permission. | Permission | Endpoints | Read-Only | Write Access | |---|---|---|---| | `CAMPAIGN_READ` | [List campaigns](/api-reference/campaigns/listCampaigns), [List leads](/api-reference/leads/listLeads) | Yes | Yes | | `CAMPAIGN_START` | [Start or resume a campaign](/api-reference/campaigns/startCampaign) | No | Yes | | `CAMPAIGN_STATUS_UPDATE` | [Pause a campaign](/api-reference/campaigns/pauseCampaign) | No | Yes | | `LEAD_CAMPAIGN_ENROLL` | [Add leads](/api-reference/leads/addLeads), [Update a lead](/api-reference/leads/updateLead), [Remove a lead](/api-reference/leads/removeLead), [Remove leads](/api-reference/leads/removeLeads) | No | Yes | | `SMTP_READ` | [List mailboxes](/api-reference/mailboxes/listMailboxes) | Yes | Yes | | `SMTP_UPDATE` | [Update a mailbox](/api-reference/mailboxes/updateMailbox) | No | Yes | Pick the role with the least access that covers what your integration does: a dashboard that only reads needs Read-Only, a CRM sync needs Write Access. ## When a key stops working [#when-a-key-stops-working] A key answers `401 unauthorized` when: - it was deleted (revoked) in **Workspace settings → Integrations**; - the person who created it left the workspace, or their account was deleted or suspended; - the workspace was archived or deleted. The answer is the same for all of them, and for a key that never existed. ## Errors [#errors] | Status | Code | Why | |---|---|---| | `401` | `unauthorized` | The `Authorization` header is missing or not `Bearer `, or the key doesn't work (see above). | | `403` | `forbidden` | The key's role lacks the permission the endpoint needs. | | `429` | `rate_limited` | Too many requests with this key. See [Rate limits](/rate-limits). | ```json { "error": { "code": "forbidden", "message": "This API key's role does not allow this request. It needs the CAMPAIGN_START permission." } } ``` ## The Alienmail MCP server uses the same keys [#the-alienmail-mcp-server-uses-the-same-keys] The [Alienmail MCP server](/guides/mcp-server) accepts the same API keys, with the same roles. AI tools that support OAuth can instead sign in with your Alienmail account and act in one workspace with your role, without a key (see [Connect by signing in](/guides/mcp-server#connect-by-signing-in)). To build that sign-in into your own app, see [Connect your own app](/guides/mcp-oauth). OAuth is for the MCP server only. The REST API on this site takes API keys. # Errors (/errors) Alienmail uses standard HTTP status codes. A `2xx` means success. Anything else has a JSON body with an `error` object: ```json { "error": { "code": "bad_request", "message": "The request is invalid. Check the fields.", "fields": { "dailyLimit": "Too big: expected number to be <=2000" } } } ``` - `code` is stable: use it in your code. - `message` is written for people and may change. - `fields` comes with validation errors, including bad query parameters like `status` or `cursor`. It maps each field to what is wrong with it. Nested fields use dots (`leads.0.firstName`, `custom.plan`), and `_` stands for the body as a whole. Unknown paths under `/api/v1` and unsupported methods answer in this format too. ## Request bodies [#request-bodies] Send bodies as JSON with the header `Content-Type: application/json`. A body with another content type is refused with `415`, and one that isn't valid JSON with `400` and the code `invalid_json`. Bodies are checked strictly. A field the endpoint doesn't know is refused with `400` instead of being ignored, so a typo like `first_name` for `firstName` can't pass silently: ```json { "error": { "code": "bad_request", "message": "The request is invalid. Check the fields.", "fields": { "leads.0": "Unrecognized key: \"first_name\"" } } } ``` ## Status codes [#status-codes] | Status | Code | Meaning | |---|---|---| | `200` | | Success. | | `400` | `bad_request` | The request is invalid. Check `fields`. | | `400` | `invalid_json` | The body isn't valid JSON. | | `401` | `unauthorized` | Missing or invalid API key. See [Authentication](/authentication). | | `403` | `forbidden` | The key's role lacks the permission the endpoint needs. | | `404` | `not_found` | The campaign, lead or mailbox doesn't exist in your workspace, or the path isn't an endpoint. An id that isn't a number, or an email that isn't an email address, is a `404` too. | | `405` | `method_not_allowed` | The endpoint doesn't support this method. The `Allow` header lists the ones it does. | | `409` | `conflict` | The campaign, lead or mailbox is in a state that doesn't allow the request. `message` says why. | | `415` | `unsupported_media_type` | The body isn't sent as `application/json`. | | `429` | `rate_limited` | Too many requests. Wait for `Retry-After` seconds. | | `500` | `server_error` | Something went wrong on our side. Retry later. | ## Conflicts [#conflicts] A `409` means the request was understood but can't be done right now. Common cases: | Request | Refused when | |---|---| | [Start a campaign](/api-reference/campaigns/startCampaign) | It is archived, its end date has passed, no email step has content, or no mailbox on it is active and connected. | | [Pause a campaign](/api-reference/campaigns/pauseCampaign) | It isn't active. | | [Add](/api-reference/leads/addLeads) or [remove](/api-reference/leads/removeLeads) leads | The campaign is archived. | | [Update a lead](/api-reference/leads/updateLead) | The campaign is completed or archived, or it is active and the lead has already been emailed. | ## Retrying [#retrying] - `429` and `5xx` are safe to retry after a pause. Back off exponentially for `5xx`. - Don't retry other `4xx` responses unchanged: they will fail the same way. - Every write in this API is safe to repeat. Adding a lead who is already in the campaign doesn't add them twice, removing one who is gone counts them in `notInCampaign`, and starting an active campaign or pausing a paused one returns it unchanged. There are no idempotency keys. # Campaigns and mailboxes (/guides/campaigns-and-mailboxes) ## Campaigns [#campaigns] [List campaigns](/api-reference/campaigns/listCampaigns) returns your workspace's campaigns, newest first, with a count of leads and of emails sent. ```bash curl "https://app.alienmail.io/api/v1/campaigns?status=active" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" ``` | Status | Meaning | |---|---| | `draft` | Not started yet. | | `active` | Sending. | | `paused` | Stopped by you. Nothing is sent until it is started again. | | `completed` | Finished its sequence, or reached its end date. | | `archived` | Put away in Alienmail. Read-only through the API. | Campaigns are created, written and scheduled in Alienmail. The API starts and pauses them. ### Start or resume [#start-or-resume] ```bash curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/start" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" ``` [Start a campaign](/api-reference/campaigns/startCampaign) works on a `draft`, `paused` or `completed` campaign and returns it with status `active`. Leads that were `pending` become `active`, and each lead's next email is queued: the first email for new leads, the next follow-up for leads part-way through. Waits between steps count from when the last email was sent, so a pause doesn't restart them. A start is refused with `409` when: - the campaign is `archived`; - its end date has passed; - none of its email steps has content; - no mailbox attached to it is active and connected. `message` says which. Starting a campaign that is already `active` returns it unchanged. ### Pause [#pause] ```bash curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/pause" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" ``` [Pause a campaign](/api-reference/campaigns/pauseCampaign) stops sending and takes the waiting emails off the queue. Only an `active` campaign can be paused; a `paused` one is returned unchanged, and any other status returns `409`. An email that is being sent at the moment you pause may still go out. ## Mailboxes [#mailboxes] [List mailboxes](/api-reference/mailboxes/listMailboxes) returns the mailboxes connected to your workspace. It never returns passwords, tokens or server settings. ```bash curl "https://app.alienmail.io/api/v1/mailboxes" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" ``` ```json { "data": [ { "id": 7, "email": "ada@analyticalengines.com", "name": "Ada from Analytical Engines", "provider": "google", "active": true, "connected": true, "rateLimited": false, "dailyLimit": 50, "sentToday": 12, "createdAt": "2026-10-01T10:00:00.000Z", "updatedAt": "2026-11-13T09:30:00.000Z" } ], "nextCursor": null } ``` | Field | Meaning | |---|---| | `active` | Whether campaigns may send from the mailbox. You set it. | | `connected` | `false` when the last connection check failed. Reconnect the mailbox in Alienmail. | | `rateLimited` | The mail provider is throttling the mailbox. | | `dailyLimit`, `sentToday` | The most emails it sends per day, and how many count against that today. | Campaigns send only from mailboxes that are both `active` and `connected`. A simple health check is to list mailboxes and alert on any with `connected: false`. ### Update a mailbox [#update-a-mailbox] [Update a mailbox](/api-reference/mailboxes/updateMailbox) changes the sender name, the daily limit (1 to 2,000) or the on/off switch. Only what you send changes. ```bash curl -X PATCH "https://app.alienmail.io/api/v1/mailboxes/7" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "dailyLimit": 30, "active": true }' ``` Mailboxes are connected, reconnected and deleted in Alienmail. Server settings, logins and passwords can't be read or changed through the API. # Connect your own app (/guides/mcp-oauth) This page is for developers who build an app, agent or MCP client that talks to the Alienmail MCP server. To connect an existing AI tool such as Claude, ChatGPT or Cursor, see [Alienmail MCP server](/guides/mcp-server). ```txt https://app.alienmail.io/api/mcp ``` ## Pick how your app signs in [#pick-how-your-app-signs-in] | | API key | OAuth | |---|---|---| | Use it when | Your own system works with your own workspace, with no person present. | Other people connect their Alienmail workspace to your app. | | Who the app acts as | The key, with the role you gave it. | The person who allowed it, with their role in the workspace they picked. | | Setup | Create a key in **Workspace settings → Integrations**. | None. Your app registers itself and sends the person to Alienmail to allow it. | | Sent as | `Authorization: Bearer YOUR_API_KEY` | `Authorization: Bearer ` | The official MCP SDKs and most MCP clients do the whole OAuth flow on this page for you: discovery, registration, PKCE and token refresh. Give them the server address and a redirect URI. Read on if you write the flow yourself or want to know what happens. ## Talk to the server [#talk-to-the-server] The server speaks MCP over Streamable HTTP. Send each JSON-RPC message as a `POST` with a JSON body, and the answer comes back as JSON in the response. A notification (a message without an `id`) is answered `202` with no body. ```bash curl https://app.alienmail.io/api/mcp \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0.0"}}}' ``` Then list the tools and call one: ```bash curl https://app.alienmail.io/api/mcp \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' curl https://app.alienmail.io/api/mcp \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_campaigns","arguments":{"status":"ACTIVE"}}}' ``` - The server offers **tools** only. `resources/list` and `prompts/list` answer empty lists. - `tools/list` returns only the tools this key or connection may call, each with its description and input schema. Read them from there; they are the source of truth. - Each tool has a `title` and `annotations`: `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`. Use them to decide which calls to confirm with the person. They are hints: the server still checks every call. - A key or connection works in one workspace, so no tool asks for a workspace id. - The older SSE transport also works: `GET` the same address with `Accept: text/event-stream`. At most 5 streams can be open at once for one key or connection. That is all an API key needs. The rest of this page is the OAuth flow. ## OAuth step by step [#oauth-step-by-step] Alienmail is its own OAuth 2.1 authorization server for the MCP server. The flow is the authorization code flow with PKCE. ### 1. Discover the endpoints [#1-discover-the-endpoints] A request without credentials is answered `401` with a header that says where to look: ```http HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer resource_metadata="https://app.alienmail.io/.well-known/oauth-protected-resource/api/mcp", scope="mcp:read mcp:write" ``` Two documents describe the rest. You can also read them directly: | Document | Address | |---|---| | Protected resource metadata (RFC 9728) | `https://app.alienmail.io/.well-known/oauth-protected-resource/api/mcp` | | Authorization server metadata (RFC 8414) | `https://app.alienmail.io/.well-known/oauth-authorization-server` | The endpoints they name: | Endpoint | Address | |---|---| | Authorization | `GET https://app.alienmail.io/api/oauth/authorize` | | Token | `POST https://app.alienmail.io/api/oauth/token` | | Registration | `POST https://app.alienmail.io/api/oauth/register` | | Revocation | `POST https://app.alienmail.io/api/oauth/revoke` | Read the addresses from the metadata in your code instead of hard-coding them. ### 2. Identify your app [#2-identify-your-app] Your app needs a `client_id`. There are two ways to get one, and neither needs an Alienmail account or an approval from us. Register once and keep the `client_id` you get back (dynamic client registration, RFC 7591): ```bash curl https://app.alienmail.io/api/oauth/register \ -H "Content-Type: application/json" \ -d '{ "client_name": "My App", "redirect_uris": ["https://myapp.example.com/oauth/callback"], "token_endpoint_auth_method": "none" }' ``` ```json { "client_id": "amc_4fJ2…", "client_id_issued_at": 1795305600, "client_name": "My App", "redirect_uris": ["https://myapp.example.com/oauth/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "scope": "mcp:read mcp:write" } ``` `token_endpoint_auth_method` decides the kind of client: - `none`: a public client, for apps that can't keep a secret (desktop, mobile, CLI, browser). It must use PKCE. - `client_secret_basic` (the default when you leave it out) or `client_secret_post`: a client with a secret, for a server. The answer then also carries a `client_secret`, shown this once. Store it; Alienmail keeps only a hash. A registration that nobody uses to connect is deleted after 30 days. Once one person allows your app, it is kept. Host a small JSON document at an `https` address and use that address as your `client_id`. Nothing to register and nothing to store. ```json { "client_id": "https://myapp.example.com/oauth/client.json", "client_name": "My App", "redirect_uris": ["https://myapp.example.com/oauth/callback"], "token_endpoint_auth_method": "none" } ``` Rules for the document: - The address is `https`, has a path, and has no port, query or fragment. - `client_id` in the document is exactly the address it is served from. - It is served as `application/json`, without a redirect, in at most 5 KB and within 5 seconds. - It is a public client: `token_endpoint_auth_method` is `none` (or left out) and there is no secret. Use PKCE. Alienmail reads the document again about once a day, so a change to your redirect URIs can take that long to apply. **Redirect URIs.** List 1 to 10. Each must be one of: - an `https://` address; - `http://localhost`, `http://127.0.0.1` or `http://[::1]` for an app on the person's own computer. The port may differ from the one you registered; - your app's own scheme, such as `myapp://oauth/callback`. A redirect URI can't contain a fragment (`#`), a user name or a password. The address you send later must match a registered one exactly. ### 3. Send the person to Alienmail [#3-send-the-person-to-alienmail] Make a PKCE pair first: a random `code_verifier` of 43 to 128 characters (`A-Z`, `a-z`, `0-9`, `-`, `.`, `_`, `~`), and a `code_challenge` that is the base64url SHA-256 of it. Keep the verifier with the person's session. ```js import crypto from 'node:crypto'; const codeVerifier = crypto.randomBytes(32).toString('base64url'); const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url'); const state = crypto.randomBytes(16).toString('base64url'); ``` Then open this address in the person's browser: ```txt https://app.alienmail.io/api/oauth/authorize ?response_type=code &client_id=amc_4fJ2… &redirect_uri=https%3A%2F%2Fmyapp.example.com%2Foauth%2Fcallback &scope=mcp%3Aread%20mcp%3Awrite &state=… &code_challenge=… &code_challenge_method=S256 ``` | Parameter | Notes | |---|---| | `response_type` | Always `code`. | | `client_id` | From step 2. | | `redirect_uri` | One you registered. Can be left out only when you registered exactly one. | | `scope` | `mcp:read`, or `mcp:read mcp:write`. Left out means both. See [Scopes](#scopes). | | `state` | Your own random value, up to 2,048 characters. Check that it comes back unchanged. | | `code_challenge`, `code_challenge_method` | PKCE. The method is always `S256`. Required for public clients. | | `resource` | Optional. If you send it, it must be `https://app.alienmail.io/api/mcp`. | The person signs in to Alienmail if they aren't already, picks the workspace your app may use, sees what it will be able to do, and chooses **Allow** or **Cancel**. They can switch off making changes, in which case your app gets `mcp:read` only. The screen stays valid for 15 minutes. Alienmail then sends the browser back to your redirect URI: ```txt https://myapp.example.com/oauth/callback?code=…&state=…&iss=https%3A%2F%2Fapp.alienmail.io ``` Check that `state` is yours and `iss` is `https://app.alienmail.io`. If the person chose Cancel, you get `error=access_denied` instead of `code`. If the request itself is wrong (unknown `client_id`, a redirect URI you didn't register, missing PKCE), Alienmail shows the person an error page that names the problem. It does not send them back to your app, so test the request in a browser while you build. ### 4. Get the tokens [#4-get-the-tokens] Exchange the code within 5 minutes. A code works once. ```bash curl https://app.alienmail.io/api/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d grant_type=authorization_code \ -d code=CODE_FROM_THE_REDIRECT \ -d redirect_uri=https://myapp.example.com/oauth/callback \ -d client_id=amc_4fJ2… \ -d code_verifier=YOUR_CODE_VERIFIER ``` A client with a secret also sends it: as HTTP Basic (`client_id` as the user name, the secret as the password) or as `client_secret` in the body. Send it one way, not both. ```json { "access_token": "amoa_…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "amor_…", "scope": "mcp:read mcp:write" } ``` `scope` is what the person allowed, which can be less than you asked for. Sending a code a second time, or with the wrong `code_verifier` or `redirect_uri`, cancels the connection it made. The person then has to allow your app again. ### 5. Call the MCP server [#5-call-the-mcp-server] Send the access token in the `Authorization` header, on every request, exactly as an API key is sent in [Talk to the server](#talk-to-the-server): ```bash curl https://app.alienmail.io/api/mcp \ -H "Authorization: Bearer amoa_…" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` Never put the token in the URL. A token in the URL is refused. ### 6. Refresh the access token [#6-refresh-the-access-token] An access token lasts one hour. When it runs out, the MCP server answers `401` with `error="invalid_token"` in `WWW-Authenticate`. Get a new one with the refresh token: ```bash curl https://app.alienmail.io/api/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d grant_type=refresh_token \ -d refresh_token=amor_… \ -d client_id=amc_4fJ2… ``` The answer has the same shape as in step 4. - **Public clients get a new refresh token every time.** Save the new one and throw the old one away. The old one still works for 60 seconds, so a retry after a lost response is safe. Using an old one after that cancels the connection, because it looks like a stolen token. - Clients with a secret keep the same refresh token. - A refresh token lasts 90 days from its last use. An app that refreshes at least once in 90 days stays connected; after that the person allows it again. ### 7. Disconnect [#7-disconnect] When a person disconnects Alienmail in your app, revoke the refresh token. This ends the whole connection: ```bash curl https://app.alienmail.io/api/oauth/revoke \ -H "Content-Type: application/x-www-form-urlencoded" \ -d token=amor_… \ -d client_id=amc_4fJ2… ``` The answer is `200` whether or not the token was still valid. The person can also disconnect your app themselves in **Workspace settings → Integrations → Connected apps**. ## Scopes [#scopes] | Scope | What the app gets | |---|---| | `mcp:read` | The tools that only read: campaigns, leads, templates, mailboxes, credits and analytics. | | `mcp:write` | Every tool the person's role allows, including the ones that create, change, delete and start. It always comes with `mcp:read`. | ## What a connection can do [#what-a-connection-can-do] - It works in **one workspace**, the one the person picked. To work with another workspace, the person connects again and picks it; each is its own connection with its own tokens. - It acts as that person, with **their role**. If their role changes, what your app can do changes with it on the next call. - `tools/list` already leaves out the tools the connection can't call. Calling one anyway returns a tool error. - `get_user_profile`, `list_workspaces` and `create_workspace` are not available to connections or API keys. - If the same person connects your app to the same workspace again, the new connection replaces the old one and the old tokens stop working. ## When a connection stops working [#when-a-connection-stops-working] The MCP server answers `401` and the token endpoint answers `invalid_grant` when: - the person, or someone who manages the workspace, disconnected your app; - the person changed or reset their Alienmail password (this ends all their connections, in every workspace); - the person left the workspace, or their account was suspended or deleted; - the workspace was archived or deleted; - your app didn't refresh for 90 days; - an old refresh token or a used code was sent again. On a `401`, refresh once. If the refresh answers `invalid_grant`, the connection is gone: drop the stored tokens and send the person through [step 3](#3-send-the-person-to-alienmail) again. ## Errors [#errors] **OAuth endpoints** (register, token, revoke) answer in the standard OAuth shape: ```json { "error": "invalid_grant", "error_description": "The code is invalid or expired." } ``` | Status | `error` | Why | |---|---|---| | `400` | `invalid_request` | A parameter is missing, repeated, or sent in the wrong format. | | `400` | `invalid_grant` | The code or refresh token is wrong, expired, used, or the connection ended. | | `400` | `invalid_scope` | A refresh asked for a scope the person didn't allow. | | `400` | `invalid_target` | `resource` is not the MCP server's address. | | `400` | `unsupported_grant_type` | `grant_type` is not `authorization_code` or `refresh_token`. | | `400` | `invalid_redirect_uri`, `invalid_client_metadata` | Registration was refused. The description says which field. | | `401` | `invalid_client` | Unknown `client_id`, a wrong or missing secret, or a secret sent by a public client. | | `429` | `rate_limited` | Too many requests. Wait for `Retry-After` seconds. | **The MCP server** answers `401` for a missing or refused token, with the `WWW-Authenticate` header shown above. **Tool calls** that fail still answer `200`, with `isError` set in the result: ```json { "jsonrpc": "2.0", "id": 3, "result": { "isError": true, "content": [{ "type": "text", "text": "Error executing tool start_campaign: …" }] } } ``` This covers a tool the role or scope doesn't allow, a wrong argument, a campaign, lead or mailbox that doesn't exist or can't change right now, and the tool-call limit (the text then says how long to wait). When Alienmail refused the request, the text starts with its status, for example `Status: 404 Not Found`, followed by the answer. ## Limits [#limits] | What | Limit | |---|---| | Tool calls | 60 per minute and 2,000 per day for each API key or connection | | Open SSE streams | 5 for each API key or connection | | Token requests | 600 per minute per IP address | | Authorization requests | 60 per minute per IP address | | Registrations | 300 per hour per IP address | | Requests with a wrong API key | 30 per minute per IP address | Over a limit, the endpoint answers `429` with `Retry-After`. Two differ: a tool call returns a tool error that says how long to wait, and the authorization endpoint shows the person an error page. Register your app once and reuse the `client_id`; don't register on every sign-in. ## Checklist [#checklist] - Read the endpoints from the metadata documents. - Use PKCE with `S256`, and check `state` and `iss` on the way back. - Store tokens on your server or in the device's secure storage, never in a URL or a log. - Save the new refresh token after every refresh. - Treat `invalid_grant` as "connect again", and tell the person. - Ask for `mcp:read` only if your app never changes anything. # Alienmail MCP server (/guides/mcp-server) Alienmail has a [Model Context Protocol](https://modelcontextprotocol.io) server. Connect it to an AI tool and the assistant can work with your workspace: list campaigns, add leads, check mailboxes and more. Sign in from the AI tool with your Alienmail account, or use an API key. ```txt https://app.alienmail.io/api/mcp ``` This is not the [docs MCP server](/ai-tools#docs-mcp-server). That one only reads this documentation and needs no key. This one acts on your account. Building your own app or agent? See [Connect your own app](/guides/mcp-oauth) for the OAuth flow, the endpoints and the errors. ## Connect by signing in [#connect-by-signing-in] Most AI tools can sign in to Alienmail for you (OAuth). You only need the server address; no key to create or paste. 1. Add `https://app.alienmail.io/api/mcp` as a connector in your AI tool (below). 2. When the tool asks, sign in to Alienmail in the browser window it opens. 3. Pick the workspace the tool may use (if you have more than one), check what it will be able to do, and choose **Allow**. In claude.ai or Claude Desktop, open **Settings → Connectors**, choose **Add custom connector**, enter `https://app.alienmail.io/api/mcp` and choose **Connect**. Leave the advanced settings (client ID and secret) empty. In ChatGPT, open **Settings → Connectors** (developer mode), create a connector with the URL `https://app.alienmail.io/api/mcp` and authentication **OAuth**. ```bash claude mcp add --transport http alienmail https://app.alienmail.io/api/mcp ``` Then run `/mcp` in Claude Code and choose **Authenticate** for `alienmail`. Add to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project, then choose **Connect** next to the server in Cursor's MCP settings: ```json { "mcpServers": { "alienmail": { "url": "https://app.alienmail.io/api/mcp" } } } ``` ### What a connected app can do [#what-a-connected-app-can-do] - It works in **the one workspace you picked**, as you, with **your role** in that workspace. It can never do more than you can, and it never sees your other workspaces. - On the screen where you allow the app, each permission has a switch. Turn off the one for creating and changing things and the app only gets the tools that read (campaigns, leads, templates, mailboxes, analytics). Connected apps then shows it as **Read** only, without **Make changes**. - `get_user_profile`, `list_workspaces` and `create_workspace` are not available to connected apps. - To use an app with another workspace, connect it again and pick that workspace. Connecting the same app to the same workspace again replaces the earlier connection. - See and disconnect connected apps in **Workspace settings → Integrations → Connected apps**. Owners and admins see every member's apps; other members see their own. A disconnected app stops at once. The app gets an access token that lasts an hour and renews itself while you keep using it; after 90 days without use you sign in again. Only a fingerprint of each token is stored. ### When a connected app stops working [#when-a-connected-app-stops-working] A connected app loses access, and asks you to sign in again, when: - you or a workspace owner or admin disconnected it in **Connected apps**; - you changed or reset your Alienmail password (this ends every app you connected, in every workspace); - you left the workspace, or your account was suspended or deleted; - the workspace was archived or deleted; - the app wasn't used for 90 days. To fix it, remove the Alienmail connector in the AI tool, add it again and sign in. If the sign-in screen says the link has expired, start again from the AI tool: the screen stays valid for 15 minutes and works once. ## Connect with an API key [#connect-with-an-api-key] For tools that can't sign in, or for automation without a person, create an [API key](/authentication#api-keys) in **Workspace settings → Integrations** and send it in the `Authorization` header. The same page in Alienmail shows these snippets with your endpoint filled in. ```bash claude mcp add --transport http alienmail https://app.alienmail.io/api/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` Add to `claude_desktop_config.json`: ```json { "mcpServers": { "alienmail": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.alienmail.io/api/mcp", "--header", "Authorization: Bearer YOUR_API_KEY"] } } } ``` Add to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project: ```json { "mcpServers": { "alienmail": { "url": "https://app.alienmail.io/api/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` Any client that supports remote MCP servers over Streamable HTTP can use `https://app.alienmail.io/api/mcp` with the header `Authorization: Bearer YOUR_API_KEY`. A client that supports OAuth for MCP can sign in instead, with only the address. For your own code, see [Connect your own app](/guides/mcp-oauth). Don't put the key in the URL. URLs end up in logs, proxies and browser history. ### What the key can do [#what-the-key-can-do] An API key works in its own workspace only, and each tool needs the same permission as the matching action in Alienmail. The tool list your AI tool receives shows only the tools the key's role allows, so a read-only key is not offered tools that change anything. Calling a tool the role doesn't allow returns an error instead of a result. Three tools work across workspaces and are not available to API keys: `get_user_profile`, `list_workspaces` and `create_workspace`. ## Tools [#tools] | Area | Tools | |---|---| | Workspace | `get_workspace_credits`, `get_workspace_analytics` | | Campaigns | `list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `duplicate_campaign`, `delete_campaign`, `start_campaign`, `toggle_campaign_status`, `update_campaign_settings` | | Sequence and templates | `get_campaign_flow`, `list_templates`, `create_template`, `get_campaign_conditions`, `create_campaign_condition` | | Leads | `list_leads`, `get_lead`, `add_lead_to_campaign`, `import_leads_csv`, `enroll_leads_in_campaign`, `bulk_enroll_leads`, `bulk_update_lead_status`, `get_lead_email_timeline`, `create_lead` (deprecated: use `add_lead_to_campaign`) | | Mailboxes | `list_smtp_accounts`, `add_smtp_account`, `update_smtp_account`, `delete_smtp_account`, `test_smtp_connection` | Your AI tool reads each tool's description and inputs from the server, so you don't need to copy them from here. Each tool also says whether it only reads, whether it deletes or can't be undone (deleting a campaign or a mailbox, changing many leads' status, starting a campaign), and whether it reaches outside Alienmail. Most AI tools use this to ask you before they run one that changes things. ## Limits [#limits] Each API key, and each connected app, can make **60 tool calls per minute and 2,000 per day**. Over the limit, the tool call returns an error that says how long to wait. Repeated requests with a wrong API key are also limited: after 30 in a minute from one IP address, the server answers `429` with a `Retry-After` header. The sign-in endpoints have their own limits, listed in [Connect your own app](/guides/mcp-oauth#limits). ## Try it [#try-it] After connecting, ask for example: - _"List my active Alienmail campaigns and how many leads each has."_ - _"Add ada@example.com to the Q1 outreach campaign."_ - _"Which of my mailboxes are disconnected?"_ The assistant acts on your real account. Give the key a role with only the access it needs (or connect the app read-only), and review what the assistant plans to do before it starts campaigns or changes leads. # Sync leads (/guides/sync-leads) A campaign emails its **leads**. This guide shows how to keep a campaign's leads in step with your CRM or product: add people when they qualify, update their details, and stop or remove them when things change. Leads are identified by **email address**. You never need to store an Alienmail id for a person. ## Find the campaign [#find-the-campaign] Every call names a campaign by its `id`. Get it from [List campaigns](/api-reference/campaigns/listCampaigns), or from the campaign's URL in Alienmail. ```bash curl "https://app.alienmail.io/api/v1/campaigns?search=outreach" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" ``` ## Add people [#add-people] [Add leads](/api-reference/leads/addLeads) takes 1 to 500 people per call. ```bash curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/leads" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "leads": [ { "email": "ada@example.com", "firstName": "Ada", "lastName": "Lovelace", "jobTitle": "Head of Engineering", "company": "Analytical Engines", "custom": { "plan": "pro", "renewal_date": "2027-01-04" } }, { "email": "grace@example.com", "firstName": "Grace" } ] }' ``` What happens to a new lead depends on the campaign: | Campaign status | What happens | |---|---| | `active` | The lead is `active` and their first email is queued at once. | | `draft` or `paused` | The lead is `pending` and starts when the campaign does. | | `completed` | The campaign becomes `active` again. Refused with `409` if it has no connected mailbox or its end date has passed. | | `archived` | Refused with `409`. | ### Read the answer [#read-the-answer] ```json { "received": 2, "added": 1, "reactivated": 0, "alreadyIn": 1, "skippedBounced": 0, "skippedUnsubscribed": 0, "invalid": [], "ignoredCustomKeys": [] } ``` | Field | Meaning | |---|---| | `added` | New leads of the campaign. | | `reactivated` | People who were removed from the campaign earlier and are back. They continue with their next email. | | `alreadyIn` | People already in the campaign. Their place in the sequence is kept; only their custom values are updated. | | `skippedBounced`, `skippedUnsubscribed` | People left out because their address bounced, or they unsubscribed, in your workspace. They can't be added back through the API. | | `invalid` | Entries that couldn't be added, each with `index`, `email` and `reason`. The other entries are still added. | | `ignoredCustomKeys` | Custom keys that couldn't become a custom column (see below). | The call is safe to repeat, so a sync job can simply send its whole segment again. A person who is already a lead in your workspace, from another campaign or an import, keeps the profile fields stored there. Adding them again doesn't overwrite `firstName`, `company` and the rest. Use [Update a lead](#update-a-lead) to change them. ### Custom values [#custom-values] `custom` holds your own values for a lead in this campaign. Use them in email text as `{{key}}`, for example `{{plan}}`. - A key that isn't a custom column of the campaign yet is added as one. It must start with a lower-case letter, use only lower-case letters, digits and underscores, be at most 40 characters, and not be a built-in variable such as `first_name` or `company`. - A campaign holds up to 50 custom columns. Keys that don't fit, or aren't valid, come back in `ignoredCustomKeys`. - Keys are lower-cased. Values are stored as text, up to 5,000 characters. ## Update a lead [#update-a-lead] [Update a lead](/api-reference/leads/updateLead) changes only what you send. `null` or an empty string clears a field. ```bash curl -X PATCH "https://app.alienmail.io/api/v1/campaigns/42/leads/ada%40example.com" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jobTitle": "CTO", "custom": { "plan": "enterprise" } }' ``` Write the email in the path with `@` as `%40`. In JavaScript, use `encodeURIComponent(email)`. Rules: - Fields and custom values can be edited while the campaign is `draft` or `paused`. In an `active` campaign they can be edited until the lead has been sent an email. After that the call returns `409`: pause the campaign, make the edit, and start it again. - In `custom`, every key must already be a custom column of the campaign. An unknown key returns `400`. - `companyDomain` must be a domain like `acme.com`, and `linkedinUrl` and `linkedinCompanyUrl` must be linkedin.com URLs. ## Stop and resume emails [#stop-and-resume-emails] To stop emailing someone without removing them, set their status: ```bash curl -X PATCH "https://app.alienmail.io/api/v1/campaigns/42/leads/ada%40example.com" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "stopped" }' ``` A `stopped` lead stays in the campaign and its lead list, and gets no more emails. Send `{ "status": "active" }` to resume them with their next email. Only `active` and `pending` leads can be stopped, and only `stopped` leads can be resumed. A lead who replied may already be `stopped`: with stop on reply turned on, Alienmail stops them itself. ## Lead statuses [#lead-statuses] | Status | Meaning | |---|---| | `pending` | Waiting for the campaign to start. | | `active` | Getting the campaign's emails. | | `stopped` | Emails stopped, by you or because they replied. Still in the campaign. | | `completed` | Finished the sequence: no more emails are due. | | `unsubscribed` | Used the unsubscribe link. | | `bounced` | Their address bounced. | | `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. You can't set it. | ## Remove people [#remove-people] [Remove a lead](/api-reference/leads/removeLead) takes one email in the path. [Remove leads](/api-reference/leads/removeLeads) takes up to 500 in the body: ```bash curl -X DELETE "https://app.alienmail.io/api/v1/campaigns/42/leads" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "emails": ["ada@example.com", "grace@example.com"] }' ``` ```json { "received": 2, "removed": 1, "notInCampaign": 1, "invalid": [] } ``` Removing cancels the emails that were waiting. The emails already sent stay in the campaign's statistics, and the person stays in your workspace's leads. Add them again later and they come back as `reactivated`. ## Read leads back [#read-leads-back] [List leads](/api-reference/leads/listLeads) returns a campaign's leads with their status, fields and custom values. Filter with `status`, or look one person up with `search`: ```bash curl "https://app.alienmail.io/api/v1/campaigns/42/leads?search=ada%40example.com" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" ``` `search` matches part of the email, first name, last name or company, so check the `email` of the results. See [Pagination](/pagination) to read every lead. # Introduction (/) Alienmail sends cold email campaigns from your own mailboxes. The API lets your CRM, product or back office work with it directly, so the right people are in the right campaign without anyone uploading a file. ## What you can build [#what-you-can-build] - **Keep campaign leads in step with your CRM.** Add people to a campaign when they match a segment, update their details, and stop or remove them when they convert. - **Control campaigns.** List your campaigns, and start or pause one from your own tools. - **Manage mailboxes.** See which mailboxes are connected and healthy, change a daily sending limit, or turn a mailbox off. - **Let an AI assistant do it.** The [Alienmail MCP server](/guides/mcp-server) gives tools like Claude and Cursor the same abilities. - **Connect your own app or agent.** Your users sign in to Alienmail from your app, and it works in their workspace through the MCP server. See [Connect your own app](/guides/mcp-oauth). ## Base URL [#base-url] All endpoints live under one base URL. Requests and responses are JSON over HTTPS. ```txt https://app.alienmail.io/api/v1 ``` ## Start here [#start-here] Create an API key and make your first requests in a few minutes. API keys, roles and the permission each endpoint needs. Add, update, stop and remove the people a campaign emails. Work with your account from Claude, Cursor and other AI tools. Sign your users in to the MCP server with OAuth, or use an API key. Every endpoint, with a playground to try it with your key. Use these docs from ChatGPT, Claude, Cursor and other AI tools. ## For tools and AI agents [#for-tools-and-ai-agents] - [`/openapi.json`](/openapi.json): the OpenAPI 3.1 spec. Import it into Postman or Insomnia, or generate a client. - [`/llms.txt`](/llms.txt) and [`/llms-full.txt`](/llms-full.txt): these docs for language models. - Every page has a Markdown version: add `.md` to its URL, or use **Copy page** at the top. # Pagination (/pagination) List endpoints return items newest first, a page at a time: ```json { "data": [ { "id": 42, "...": "..." } ], "nextCursor": "38" } ``` | Parameter | Description | |---|---| | `limit` | Items per page, 1 to 100. Default 25. A number outside that range is rounded to the nearest limit (`0` gives 1, `500` gives 100), a fraction is rounded down, and anything that isn't a number (including an empty `limit=`) gives the default. | | `cursor` | The `nextCursor` of the previous page. Leave it out for the first page. Any other value returns `400`. | `nextCursor` is `null` on the last page. Cursors stay valid: items created after you started don't shift your pages. ## Read every page [#read-every-page] ```js async function* allLeads(campaignId) { let cursor = null; do { const url = new URL(`https://app.alienmail.io/api/v1/campaigns/${campaignId}/leads`); url.searchParams.set('limit', '100'); if (cursor) url.searchParams.set('cursor', cursor); const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ALIENMAIL_API_KEY}` } }); if (!res.ok) throw new Error(`Alienmail API: ${res.status}`); const page = await res.json(); yield* page.data; cursor = page.nextCursor; } while (cursor); } ``` Reading everything uses one request per 100 items. Mind the [rate limit](/rate-limits). # Quickstart (/quickstart) ### Create an API key [#create-an-api-key] In Alienmail, open **Workspace settings → Integrations** and find **API keys**. Enter a key name (like "CRM sync"), pick the **Write Access Key** [role](/authentication#roles-and-permissions) so the key can add leads, and create the key. The key is shown **only once**, so copy it now and keep it in your server's secrets. The examples below read it from an environment variable: ```bash export ALIENMAIL_API_KEY="paste your key here" ``` Use API keys only from your servers. Never put them in a web page, a mobile app or a public repository. ### Make your first request [#make-your-first-request] List your campaigns, newest first. ```bash curl "https://app.alienmail.io/api/v1/campaigns?limit=5" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" ``` ```js const res = await fetch('https://app.alienmail.io/api/v1/campaigns?limit=5', { headers: { Authorization: `Bearer ${process.env.ALIENMAIL_API_KEY}` }, }); const { data, nextCursor } = await res.json(); ``` ```python import os, requests res = requests.get( "https://app.alienmail.io/api/v1/campaigns", params={"limit": 5}, headers={"Authorization": f"Bearer {os.environ['ALIENMAIL_API_KEY']}"}, ) print(res.json()) ``` You get a page of campaigns: ```json { "data": [ { "id": 42, "name": "Q1 outreach", "status": "active", "leadCount": 180, "sentCount": 412, "lastSentAt": "2026-11-13T09:30:00.000Z", "createdAt": "2026-11-02T08:15:00.000Z", "updatedAt": "2026-11-13T09:30:00.000Z" } ], "nextCursor": null } ``` Note the `id` of the campaign you want to work with. It is also the number in the campaign's URL in Alienmail. ### Add a lead to a campaign [#add-a-lead-to-a-campaign] Send people by email address. Replace `42` with your campaign id. ```bash curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/leads" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "leads": [ { "email": "ada@example.com", "firstName": "Ada", "lastName": "Lovelace", "company": "Analytical Engines", "custom": { "plan": "pro" } } ] }' ``` The answer says what happened to each person: ```json { "received": 1, "added": 1, "reactivated": 0, "alreadyIn": 0, "skippedBounced": 0, "skippedUnsubscribed": 0, "invalid": [], "ignoredCustomKeys": [] } ``` Calling it again with the same person is safe: they are counted in `alreadyIn` and not added twice. See [Sync leads](/guides/sync-leads) for the full rules. ### Stop emailing someone [#stop-emailing-someone] When a lead becomes a customer, stop their emails. The lead is addressed by email, with `@` written as `%40`. ```bash curl -X PATCH "https://app.alienmail.io/api/v1/campaigns/42/leads/ada%40example.com" \ -H "Authorization: Bearer $ALIENMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "stopped" }' ``` ### Try any endpoint in the browser [#try-any-endpoint-in-the-browser] Every page of the [API reference](/api-reference) has a playground. Paste your key in **Authorization**, fill in the fields and press **Send** to see the real response. The playground calls the live API with your key, so writes are real. Use a test campaign while you explore. ## Next steps [#next-steps] Roles, permissions and key errors. Start and pause campaigns, and manage mailboxes. # Rate limits (/rate-limits) Each API key can make **120 requests per minute**. Keys don't share the limit, so two systems with their own keys don't slow each other down. The count starts over each minute. Over the limit, the API answers `429` with a `Retry-After` header, in seconds: ```http HTTP/1.1 429 Too Many Requests Retry-After: 42 Content-Type: application/json { "error": { "code": "rate_limited", "message": "Too many API requests: the limit is 120 per minute for this key. Try again in 42 seconds." } } ``` ## Adding and removing leads [#adding-and-removing-leads] [Add leads](/api-reference/leads/addLeads) and [Remove leads](/api-reference/leads/removeLeads) have a second limit that all keys of a workspace share: **120 calls per minute and 5,000 calls per day**. Each call can carry up to 500 people, so this is rarely reached. It answers with the same `429`. ## Staying under the limit [#staying-under-the-limit] - Wait for `Retry-After` before trying again. - Send leads in batches: up to 500 people per [Add leads](/api-reference/leads/addLeads) call, not one call per person. - Use `limit=100` when reading lists. ## The MCP server [#the-mcp-server] The [Alienmail MCP server](/guides/mcp-server) has its own limit: 60 tool calls per minute and 2,000 per day for each API key, and the same for each app connected by signing in. The limits on its sign-in endpoints are in [Connect your own app](/guides/mcp-oauth#limits). # List campaigns (/api-reference/campaigns/listCampaigns) ## List campaigns `GET https://app.alienmail.io/api/v1/campaigns` The campaigns of your workspace, newest first. Archived campaigns are included; deleted ones are not. Requires the `CAMPAIGN_READ` permission. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `status` | query | "draft" \| "active" \| "paused" \| "completed" \| "archived" | no | Only campaigns with this status. | | `search` | query | string | no | Only campaigns whose name contains this text. | | `limit` | query | integer | no | 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. | | `cursor` | query | string | no | The `nextCursor` of the previous page. Anything else returns 400. | ### Responses **200**: A page of campaigns. ```json { "data": [ { "id": 42, "name": "Q1 outreach", "status": "active", "leadCount": 180, "sentCount": 412, "lastSentAt": "2026-11-13T09:30:00.000Z", "createdAt": "2026-11-13T09:30:00.000Z", "updatedAt": "2026-11-13T09:30:00.000Z" } ], "nextCursor": null } ``` **400**: The request is invalid: `fields` names the parameters to fix. **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page. # Start or resume a campaign (/api-reference/campaigns/startCampaign) ## Start or resume a campaign `POST https://app.alienmail.io/api/v1/campaigns/{id}/start` 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. It 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. Requires the `CAMPAIGN_START` permission. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | integer | yes | 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. | ### Responses **200**: The campaign, now `active`. ```json { "id": 42, "name": "Q1 outreach", "status": "active", "leadCount": 180, "sentCount": 412, "lastSentAt": "2026-11-13T09:30:00.000Z", "createdAt": "2026-11-13T09:30:00.000Z", "updatedAt": "2026-11-13T09:30:00.000Z" } ``` **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **404**: The campaign, lead or mailbox was not found in your workspace. **409**: The campaign, lead or mailbox is in a state that does not allow this. `message` says why. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page. # Pause a campaign (/api-reference/campaigns/pauseCampaign) ## Pause a campaign `POST https://app.alienmail.io/api/v1/campaigns/{id}/pause` 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. Only an `active` campaign can be paused. Any other status returns 409. Requires the `CAMPAIGN_STATUS_UPDATE` permission. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | integer | yes | 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. | ### Responses **200**: The campaign, now `paused`. ```json { "id": 42, "name": "Q1 outreach", "status": "active", "leadCount": 180, "sentCount": 412, "lastSentAt": "2026-11-13T09:30:00.000Z", "createdAt": "2026-11-13T09:30:00.000Z", "updatedAt": "2026-11-13T09:30:00.000Z" } ``` **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **404**: The campaign, lead or mailbox was not found in your workspace. **409**: The campaign, lead or mailbox is in a state that does not allow this. `message` says why. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page. # List leads (/api-reference/leads/listLeads) ## List leads `GET https://app.alienmail.io/api/v1/campaigns/{id}/leads` The leads of a campaign, newest first. Leads that were removed from the campaign are not listed. Requires the `CAMPAIGN_READ` permission. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | integer | yes | 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. | | `status` | query | "pending" \| "active" \| "stopped" \| "completed" \| "unsubscribed" \| "bounced" \| "skipped" | no | Only leads with this status. | | `search` | query | string | no | Only leads whose email, first name, last name or company contains this text. Search for a full email address to look up one lead. | | `limit` | query | integer | no | 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. | | `cursor` | query | string | no | The `nextCursor` of the previous page. Anything else returns 400. | ### Responses **200**: A page of leads. ```json { "data": [ { "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" } ], "nextCursor": null } ``` **400**: The request is invalid: `fields` names the parameters to fix. **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **404**: The campaign, lead or mailbox was not found in your workspace. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page. # Add leads (/api-reference/leads/addLeads) ## Add leads `POST https://app.alienmail.io/api/v1/campaigns/{id}/leads` 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. The 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. An 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. Requires the `LEAD_CAMPAIGN_ENROLL` permission. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | integer | yes | 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. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `leads` | object[] | yes | 1 to 500 people. When an email appears twice, the first entry is used. | Example: ```json { "leads": [ { "email": "ada@example.com", "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" } } ] } ``` ### Responses **200**: What happened to the people in the request. ```json { "received": 2, "added": 2, "reactivated": 0, "alreadyIn": 0, "skippedBounced": 0, "skippedUnsubscribed": 0, "invalid": [], "ignoredCustomKeys": [] } ``` **400**: The request is invalid: `fields` names the fields to fix. Code `invalid_json` when the body is not valid JSON. **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **404**: The campaign, lead or mailbox was not found in your workspace. **409**: The campaign, lead or mailbox is in a state that does not allow this. `message` says why. **415**: The body is not JSON: send it with `Content-Type: application/json`. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page. # Remove leads (/api-reference/leads/removeLeads) ## Remove leads `DELETE https://app.alienmail.io/api/v1/campaigns/{id}/leads` 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. Emails that are not leads of the campaign are counted in `notInCampaign`, so the call is safe to repeat. An `archived` campaign returns 409. Requires the `LEAD_CAMPAIGN_ENROLL` permission. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | integer | yes | 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. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `emails` | string[] | yes | 1 to 500 email addresses to remove from the campaign. | Example: ```json { "emails": [ "ada@example.com", "grace@example.com" ] } ``` ### Responses **200**: What happened to the emails in the request. ```json { "received": 2, "removed": 1, "notInCampaign": 1, "invalid": [] } ``` **400**: The request is invalid: `fields` names the fields to fix. Code `invalid_json` when the body is not valid JSON. **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **404**: The campaign, lead or mailbox was not found in your workspace. **409**: The campaign, lead or mailbox is in a state that does not allow this. `message` says why. **415**: The body is not JSON: send it with `Content-Type: application/json`. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page. # Update a lead (/api-reference/leads/updateLead) ## Update a lead `PATCH https://app.alienmail.io/api/v1/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. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | integer | yes | 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` | path | string | yes | The lead email address. Encode it for a URL (`@` as `%40`). Upper and lower case are treated the same. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `firstName` | string \| null | no | First name. Up to 191 characters. `null` or an empty string clears it. | | `lastName` | string \| null | no | Last name. Up to 191 characters. `null` or an empty string clears it. | | `salutation` | string \| null | no | How to address them, like `Dr.` or `Ms.`. Up to 191 characters. `null` or an empty string clears it. | | `jobTitle` | string \| null | no | Job title. Up to 191 characters. `null` or an empty string clears it. | | `department` | string \| null | no | Department. Up to 191 characters. `null` or an empty string clears it. | | `seniority` | string \| null | no | Seniority level. Up to 191 characters. `null` or an empty string clears it. | | `phone` | string \| null | no | Phone number, in any format. Up to 191 characters. `null` or an empty string clears it. | | `linkedinUrl` | string \| null | no | LinkedIn profile URL. Up to 191 characters. `null` or an empty string clears it. | | `gender` | string \| null | no | Gender. Up to 191 characters. `null` or an empty string clears it. | | `timezone` | string \| null | no | Time zone. Up to 191 characters. `null` or an empty string clears it. | | `language` | string \| null | no | Language. Up to 191 characters. `null` or an empty string clears it. | | `company` | string \| null | no | Company name. Up to 191 characters. `null` or an empty string clears it. | | `companyDomain` | string \| null | no | Company website domain. Up to 191 characters. `null` or an empty string clears it. | | `industry` | string \| null | no | Industry. Up to 191 characters. `null` or an empty string clears it. | | `companySize` | string \| null | no | Company size, as text. Up to 191 characters. `null` or an empty string clears it. | | `revenue` | string \| null | no | Company revenue, as text. Up to 191 characters. `null` or an empty string clears it. | | `linkedinCompanyUrl` | string \| null | no | LinkedIn company page URL. Up to 191 characters. `null` or an empty string clears it. | | `city` | string \| null | no | City. Up to 191 characters. `null` or an empty string clears it. | | `state` | string \| null | no | State or region. Up to 191 characters. `null` or an empty string clears it. | | `country` | string \| null | no | Country. Up to 191 characters. `null` or an empty string clears it. | | `countryCode` | string \| null | no | Country code. Up to 191 characters. `null` or an empty string clears it. | | `description` | string \| null | no | Notes about this person. Up to 5000 characters; only your workspace sees them. `null` or an empty string clears it. | | `custom` | object | no | 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` | "active" \| "stopped" | no | `stopped` stops emails to this lead; they stay in the campaign. `active` resumes a stopped lead. | Example: ```json { "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": "enterprise" }, "status": "stopped" } ``` ### Responses **200**: The updated lead. ```json { "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" } ``` **400**: The request is invalid: `fields` names the fields to fix. Code `invalid_json` when the body is not valid JSON. **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **404**: The campaign, lead or mailbox was not found in your workspace. **409**: The campaign, lead or mailbox is in a state that does not allow this. `message` says why. **415**: The body is not JSON: send it with `Content-Type: application/json`. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page. # Remove a lead (/api-reference/leads/removeLead) ## Remove a lead `DELETE https://app.alienmail.io/api/v1/campaigns/{id}/leads/{email}` 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. Requires the `LEAD_CAMPAIGN_ENROLL` permission. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | integer | yes | 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` | path | string | yes | The lead email address. Encode it for a URL (`@` as `%40`). Upper and lower case are treated the same. | ### Responses **200**: The lead was removed. ```json { "removed": true } ``` **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **404**: The campaign, lead or mailbox was not found in your workspace. **409**: The campaign, lead or mailbox is in a state that does not allow this. `message` says why. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page. # List mailboxes (/api-reference/mailboxes/listMailboxes) ## List mailboxes `GET https://app.alienmail.io/api/v1/mailboxes` The mailboxes connected to your workspace, newest first. Passwords, tokens and server settings are never returned. Requires the `SMTP_READ` permission. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer | no | 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. | | `cursor` | query | string | no | The `nextCursor` of the previous page. Anything else returns 400. | ### Responses **200**: A page of mailboxes. ```json { "data": [ { "id": 7, "email": "ada@analyticalengines.com", "name": "Ada from Analytical Engines", "provider": "google", "active": true, "connected": true, "rateLimited": false, "dailyLimit": 50, "sentToday": 12, "createdAt": "2026-11-13T09:30:00.000Z", "updatedAt": "2026-11-13T09:30:00.000Z" } ], "nextCursor": null } ``` **400**: The request is invalid: `fields` names the parameters to fix. **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page. # Update a mailbox (/api-reference/mailboxes/updateMailbox) ## Update a mailbox `PATCH https://app.alienmail.io/api/v1/mailboxes/{id}` 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. Requires the `SMTP_UPDATE` permission. Authentication: `Authorization: Bearer ` ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | integer | yes | The mailbox id, from the mailbox list. | ### Request body | Field | Type | Required | Description | |---|---|---|---| | `name` | string | no | The sender name recipients see. | | `dailyLimit` | integer | no | Most emails this mailbox sends per day, 1 to 2000. | | `active` | boolean | no | `false` stops sending from this mailbox; `true` turns it back on. | Example: ```json { "name": "Ada from Analytical Engines", "dailyLimit": 50, "active": true } ``` ### Responses **200**: The updated mailbox. ```json { "id": 7, "email": "ada@analyticalengines.com", "name": "Ada from Analytical Engines", "provider": "google", "active": true, "connected": true, "rateLimited": false, "dailyLimit": 50, "sentToday": 12, "createdAt": "2026-11-13T09:30:00.000Z", "updatedAt": "2026-11-13T09:30:00.000Z" } ``` **400**: The request is invalid: `fields` names the fields to fix. Code `invalid_json` when the body is not valid JSON. **401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted. **403**: The API key's role lacks the permission this endpoint needs. **404**: The campaign, lead or mailbox was not found in your workspace. **409**: The campaign, lead or mailbox is in a state that does not allow this. `message` says why. **415**: The body is not JSON: send it with `Content-Type: application/json`. **429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads. Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page.