Hi {{first_name}}, …
" }, { "subject": "{{first_name}}, an idea for {{company_name}}", "body": "Hi {{first_name}}, …
" } ] }, { "subject": "Following up", "body": "Just circling back.
", "delayDays": 3 } ], "accounts": ["123e4567-e89b-12d3-a456-426614174000"], "tags": ["8debf023-6c1e-4b7a-9f3d-2a1b0c9d8e7f"], "leads": ["jane@acme.com", "sam@globex.com"], "launch": false }' ``` > [!NOTE] > > `sendingMinutesStart` / `sendingMinutesEnd` are minutes from midnight in the > campaign timezone, in 30-minute steps - `540` = 09:00, `1020` = 17:00, `1440` = > midnight, and the start must be before the end. Step delays are counted from > the previous step; the first step sends immediately when a lead enters. > `endDate` is optional: the campaign sends until the end of that day in its > timezone and then completes, and it can't be before `startDate`. On `PATCH`, > `"endDate": null` removes it. ### Campaigns that keep receiving leads By default a campaign completes once every lead has received every step. Leads added after that are not sent until someone restarts the campaign in the dashboard - the API cannot restart a completed campaign. If leads keep arriving over time - for example an automation that calls `POST /v1/campaigns/{id}/leads` every day - set `"keepActiveWhenNoLeads": true` in `settings` (in the dashboard: Settings → Advanced → Campaign Completion): ```json theme={null} "settings": { "keepActiveWhenNoLeads": true } ``` The campaign then stays `active` when it runs out of leads and starts scheduling new leads as soon as they are added - no restart needed. It still completes on its `endDate`, and you can pause or delete it as usual. Switch it on for an existing campaign with `PATCH /v1/campaigns/{id}` before its leads run out - it does not reopen a campaign that has already completed. `/start` needs at least one lead, so add the first leads before starting; an empty campaign cannot be started to wait for them. ### Per-day windows (advanced schedule) Instead of one window for all `sendingDays`, you can give each day its own windows - the same "Advanced schedule" as in the dashboard. Pass `intervals` (this implies `"mode": "advanced"`); `day` is `1` = Monday … `7` = Sunday and times are minutes from midnight in the campaign timezone. A shifted week - Monday from 09:30, Tuesday from 10:30, and so on: ```json theme={null} "schedule": { "timezone": "America/New_York", "intervals": [ { "day": 1, "startMinutes": 570, "endMinutes": 1050 }, { "day": 2, "startMinutes": 630, "endMinutes": 1110 }, { "day": 3, "startMinutes": 690, "endMinutes": 1170 }, { "day": 4, "startMinutes": 750, "endMinutes": 1230 }, { "day": 5, "startMinutes": 810, "endMinutes": 1290 } ] } ``` Rules (a violation is a `400`, nothing is changed): * up to 50 windows; a day may have several, but they must not overlap; * start and end on a 30-minute step, each window at least 30 minutes long; * at least one window must be enabled (`enabled` defaults to `true`). `intervals` **replaces** all existing windows. `"mode": "simple"` switches back to `sendingDays` + `sendingMinutesStart`/`sendingMinutesEnd` and keeps the windows for later; `"mode": "advanced"` alone re-enables the saved ones. Every campaign response reports `schedule.mode` and `schedule.intervals`. ### A/B variants A step is either one email (`subject` + `body`) or an A/B test: `variants`, up to **5**, lettered `A`, `B`, `C`… in the order you pass them - the same as the sequence editor in the dashboard. Leads are split **evenly** between the active variants of a step (two → 50% each, three → 33.33%). A variant with `"isActive": false` is kept but not sent; at least one per step must stay active. A variant without `isActive` is on - when you send variants back, pass each one's `isActive` as the campaign shows it, or a switched-off variant starts sending again. ```json theme={null} "sequence": [ { "variants": [ { "subject": "Quick question about {{company_name}}", "body": "…
" }, { "subject": "Idea for {{company_name}}", "body": "…
" }, { "subject": "{{first_name}}?", "body": "…
", "isActive": false } ] }, { "subject": "Following up", "body": "…
", "delayDays": 3 } ] ``` Pass either `variants` or `subject` + `body` on a step, not both (`400`). A step read back from `GET` shows its variant A as `subject` + `body` next to `variants`; when you send the step back, send only its `variants`. With `settings.abTestingOptimization: true`, once every active variant of a step has at least 1000 sends, the variant with the best reply rate is kept and the others are switched off - `variants[].isActive` shows the result. ### Settings `settings` holds everything on the campaign's **Settings** page. Every field is optional; on `PATCH` only the fields you pass change. A new campaign starts with the defaults below. | Field | Default | What it does | | - | - | - | | `useAllAccounts` | `true` | Send from every connected mailbox, or (`false`) only from `accounts`. | | `stopOnReply` | `true` | Stop follow-ups to a lead once they reply. | | `stopOnBounce` | `true` | Stop sending to a lead whose email hard-bounced. | | `stopCompanyOnReply` | `true` | A reply stops the sequence for every lead of the same company email domain (public domains such as gmail.com never match). | | `highBounceAutoProtection` | `false` | Pause the campaign when its hard-bounce rate over the last 24 hours goes above 5%. | | `skipInvalidEmails` | `true` | Skip leads whose email verification is `invalid`. | | `skipUnknownEmails` | `true` | Skip leads whose email verification is `unknown`. | | `skipRiskyEmails` | `false` | Skip leads whose email verification is `risky` (catch-all domain). | | `trackOpens` | `false` | Track opens. Not available with `sendAsTextOnly`. | | `trackClicks` | `false` | Track link clicks. Not available with `sendAsTextOnly`. | | `sendAsTextOnly` | `false` | Send plain text only, no HTML part. | | `sendFirstAsText` | `false` | Send the first step as plain text, follow-ups as HTML. The first email is then not tracked and has no body unsubscribe link (the `List-Unsubscribe` header still applies). | | `emailProviderMatching` | `false` | Prefer a sending mailbox on the lead's provider (Google to Google, Outlook to Outlook). | | `unsubscribeLinkHeader` | `false` | Add the one-click `List-Unsubscribe` header (RFC 8058). | | `unsubscribeLinkBody` | `false` | Add an unsubscribe link at the bottom of the email body. | | `autoBlacklistOnUnsubscribe` | `false` | Also add a lead who unsubscribes to the workspace blacklist. | | `newLeadsRatio` | `80` | Percent (0-100) of daily sending that goes to first emails for new leads; the rest is follow-ups. `0` contacts no new leads. | | `abTestingOptimization` | `false` | Keep the best-replying variant of each step automatically (see above). | | `hubspotSyncEnabled` | `true` | Let the recurring HubSpot sync add contacts to this campaign (only matters when HubSpot is connected). | | `keepActiveWhenNoLeads` | `false` | Keep the campaign active when it runs out of leads and schedule leads added later (see [Campaigns that keep receiving leads](#campaigns-that-keep-receiving-leads)). | The text modes follow the dashboard's rules: `sendAsTextOnly` and `sendFirstAsText` exclude each other - turning one on turns the other off, and both `true` in one request is a `400`. A plain-text-only email has no HTML for an open pixel, tracked links or a body unsubscribe link, so turning `sendAsTextOnly` on turns `trackOpens`, `trackClicks` and `unsubscribeLinkBody` off, and asking for any of them as `true` while it is on is a `400`. To track the follow-ups but keep the first email plain, use `sendFirstAsText`. Every field may be left out, and `null` counts as left out (the current value stays) everywhere except `schedule.endDate`, where `null` removes the end date. The response returns the created campaign plus a lead-ingest summary: ```json Response theme={null} { "campaign": { "id": "333e9ef7-734d-40b2-9e3f-cbce63411b69", "name": "Q4 Product Launch Outreach", "status": "draft", "schedule": { "timezone": "America/New_York", "dailyLimit": 50, "…": "…" }, "settings": { "trackOpens": true, "stopOnReply": true, "useAllAccounts": false, "skipRiskyEmails": true, "…": "every field from the table above" }, "metrics": { "leadsCount": 2, "sent": 0, "opens": 0, "clicks": 0, "replies": 0 }, "sequence": [ { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "subject": "Quick question about {{company_name}}", "body": "Hi {{first_name}}, …
", "delayDays": 0, "delayHours": 0, "variants": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "label": "A", "subject": "Quick question about {{company_name}}", "body": "…", "isActive": true }, { "id": "6c1e8b2a-4f3d-4e5a-9b8c-7d6e5f4a3b2c", "label": "B", "subject": "{{first_name}}, an idea for {{company_name}}", "body": "…", "isActive": true } ] } ], "accounts": ["123e4567-e89b-12d3-a456-426614174000"], "tags": [ { "id": "8debf023-6c1e-4b7a-9f3d-2a1b0c9d8e7f", "name": "q4-launch", "color": "#10B981" } ] }, "leads": { "submitted": 2, "created": 2, "duplicates": 0, "invalid": 0 }, "launched": false } ``` ## Subsequences A campaign can have [subsequences](/subsequences): follow-up flows that start when a lead replies, gets a status (e.g. *Interested*, *Out of office*), opens, clicks, or finishes the sequence without replying. `GET /v1/campaigns/{id}` lists them as `"subsequences": [{ "id", "name", "status" }]` (an empty array when there are none); manage them under `/v1/campaigns/{id}/subsequences` and `/v1/subsequences/{id}`. A subsequence is not a campaign in this API: it is not in `GET /v1/campaigns`, and `/v1/campaigns/{id}…` answers `404` for its id. ## Launch and control sending Drive the send lifecycle through explicit routes - `/start`, `/pause`, or `/resume`. To end a campaign, pause it (or delete it); completion otherwise happens automatically when the end date passes or every lead has been sent (unless `settings.keepActiveWhenNoLeads` is on - then only the end date completes it). ```bash theme={null} curl -X POST https://api.mailbeast.ai/v1/campaigns/{id}/start \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` You can also launch at creation time by passing `"launch": true` in the create body (requires `campaigns:lifecycle`). > [!NOTE] > > A campaign must have **at least one lead and a sequence** to start. A launch > attempt without them is rejected `400` on `POST /start`; on create-with-`launch` > the campaign is still created and returned as a draft (`201`, `launched: false`, > with a `launchError`). `/start`, `/pause` and `/resume` answer `409 campaign_busy` when the campaign is being changed right now - retry after `Retry-After` - and `409 campaign_state_changed` when it changed (for example completed) while the request ran - read it again before retrying. ## Send a test email Before you launch, send yourself a rendered preview of one step variant, from a real mailbox, exactly as a lead would receive it. Take the `variantId` from `sequence[].variants[].id` on the campaign (`GET /v1/campaigns/{id}`, or the create response). A step written with `subject` + `body` has one variant, labelled `A`; an A/B step has one per variant. Replacing the `sequence` with `PATCH` rebuilds the steps, so step and variant ids change - read the campaign again before sending a test. ```bash theme={null} curl -X POST https://api.mailbeast.ai/v1/campaigns/{id}/test-email \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "variantId": "550e8400-e29b-41d4-a716-446655440000", "accountId": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "recipient": "you@acme.com", "personalization": "dummy" }' ``` ```json Response theme={null} { "sent": true, "messageId": "Thanks for the details, this works for us.
", "text": "Thanks for the details, this works for us." } } ``` ## Reply and forward `POST /v1/emails/{id}/reply` answers in the conversation the email belongs to. You supply the body; the sender and the recipient are decided for you. The reply goes out from the mailbox that owns the conversation and is addressed to the other party, so a reply can never turn into a message to someone else. ```bash theme={null} curl -X POST https://api.mailbeast.ai/v1/emails/{id}/reply \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "body": { "text": "Happy to set up a call. Does Thursday work?" }, "cc": ["cto@acme.com"] }' ``` ```json Response theme={null} { "id": "5e9a3c81-7d24-4b60-9f13-8a6c2e0d4b57", "threadId": "13a265fd-f0f2-b1d1-d6fc-154e483183e7", "status": "queued" } ``` `POST /v1/emails/{id}/forward` sends the message on to recipients you choose, with the original quoted below your note. It also goes out from the mailbox that owns the conversation. ```bash theme={null} curl -X POST https://api.mailbeast.ai/v1/emails/{id}/forward \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": ["colleague@acme.com"], "body": { "text": "FYI, worth a look." } }' ``` ### Recipients you add are checked against your blocklist Anyone you name yourself – `cc` and `bcc` on a reply, `to`, `cc` and `bcc` on a forward – is checked against your workspace blocklist. If one of them is on it, the whole request is refused with `400` and nothing is sent; the message names every blocked address, so you can fix the list in one pass. ## Read state `isUnread` on an email means "this message arrived after the last time its conversation was read". A conversation can therefore hold both read and unread messages at once, which is exactly what you want when polling: it tells you which replies are new, not merely which conversations have something new in them. You **read** that state per email, and you **clear** it per conversation. `POST /v1/threads/{id}/read` marks every email in a conversation as read. It is the only write there is for read state, and it is the same action a person takes by opening the conversation in the dashboard, so what you do through the API and what your team sees stay in step. ```bash theme={null} curl -X POST https://api.mailbeast.ai/v1/threads/{id}/read \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` # Idempotency Source: https://developer.mailbeast.ai/idempotency Retry writes safely - 24h response replay, plus durable dedup for quota and leads. Network calls fail in ambiguous ways - a request times out, but you can't tell whether the server processed it. Sending an `Idempotency-Key` lets you retry safely: within a 24-hour window the API replays the original response instead of running the operation again. Send the header on any mutating request (`POST`, `PATCH`, `DELETE`). If you retry with the **same key**, you get the original response back: ```bash theme={null} curl https://api.mailbeast.ai/v1/campaigns \ -H "Authorization: Bearer mb_live_…" \ -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \ -H "Content-Type: application/json" \ -d '{ "name": "Q3 outreach" }' ``` Retry that request within the window and the second call returns the same body with an extra header instead of creating another campaign: ``` X-Idempotency-Replayed: true ``` > [!NOTE] > > Idempotency is **opt-in**. A request with no `Idempotency-Key` header behaves > normally - nothing is cached and every call runs. Reads (`GET`) are already > idempotent and ignore the header. ## How it works * **Generate a unique key per operation** - a UUID is ideal. Use one key for one logical write, and reuse it only when retrying that same write. * **Keys are scoped to your workspace** - a key you use never collides with another workspace's, and the scope is derived server-side from your API key. * **Only successful (`2xx`) responses are cached.** If the first attempt failed, retrying with the same key genuinely re-runs the operation. > [!NOTE] > > **Exception - creating an API key is *not* idempotent.** Its response contains a > one-time token that is never stored in retrievable form, so it cannot be replayed. > An `Idempotency-Key` on `POST /v1/api-keys` is ignored, and a retry mints a **new** > key - delete any extras ([list](/api-reference/api-keys/list-api-keys) them first). ## Edge cases | Situation | Result | | - | - | | Same key, **same** body | Original response replayed (`X-Idempotency-Replayed: true`) | | Same key, **different** body | `422` - the key is already bound to a different request | | Same key, two requests **in flight** at once | The second returns `409` while the first is still processing | | Key longer than 255 characters | `400` | | `reply` / `forward` / `test-email` while duplicate protection is briefly unavailable | `503` with `Retry-After` - **nothing was sent**, retry with the same key | > [!NOTE] > > **Email sends never run unprotected.** Other writes go through even if duplicate > protection is briefly unavailable - a stray duplicate draft is easy to clean up. > An email cannot be unsent, so `POST /v1/emails/{id}/reply`, `/forward` and > `POST /v1/campaigns/{id}/test-email` sent with an `Idempotency-Key` refuse with > `503` instead. The retry is safe. A `422` from a body mismatch looks like this: ```json theme={null} { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "Idempotency-Key already used with a different request body.", "status": 422, "requestId": "…" } } ``` # Overview Source: https://developer.mailbeast.ai/introduction One API for the full local lead-gen & cold-outreach loop. The MailBeast API is a **task-shaped** REST API: each endpoint maps to a job you actually do - connect a mailbox, launch a campaign, load leads, read replies, discover new leads - not to an internal database table. > [card] Base URL > > `https://api.mailbeast.ai` > [card] Auth > > `Authorization: Bearer mb_live…` ## Design principles These principles shape every endpoint as it ships: * **Composites over ceremony.** Create a fully-configured, optionally-live campaign in **one** call instead of six. * **One-or-many bodies.** Ingest endpoints accept a single object *or* an array of the same shape. * **Cursor pagination** on every list. **Least-privilege scopes** on every route. * **One error envelope** everywhere: `{ "error": { "type", "code", "message", "status", "requestId" } }`, plus an optional `details[]` on validation errors and `retryAfter` on `429`s. > [card] [Get started](/quickstart) > > Create a key and make your first authenticated call in two steps. # Lead Finder Source: https://developer.mailbeast.ai/lead-finder List past lead searches and poll a running search's progress. Lead Finder discovers new companies and leads from a natural-language query. This first release exposes the two **reads** you need to follow a search that was started in the dashboard: list your past searches, and poll one search's status and progress while it runs. > [!NOTE] > > Starting, stopping, and pulling results from a search over the API is coming in a later > release. For now you create and drive a search in the dashboard, and read its state here. ## Scopes | Action | Scope | | - | - | | List searches, read one search | `leadfinder:read` | ### Pagination The list is cursor-paginated and stable under concurrent changes. When `meta.hasMore` is `true`, pass `meta.nextCursor` back as `?cursor=` to fetch the next page; it is `null` on the last page. Cursors are opaque – do not parse or build them by hand. ```bash theme={null} curl "https://api.mailbeast.ai/v1/lead-searches?cursor=eyJ0cyI6..." \ -H "Authorization: Bearer mb_live_..." ``` `limit` defaults to 50 and caps at 100. ## Get one search ```bash theme={null} curl "https://api.mailbeast.ai/v1/lead-searches/{id}" \ -H "Authorization: Bearer mb_live_..." ``` This is the **single poll target** while a search runs. It returns the search's status plus live progress counters. ```json theme={null} { "id": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "query": "dental clinics in Berlin", "status": "processing", "searchMode": "companies", "maxResults": 500, "discoveryFinished": false, "progress": { "companiesFound": 84, "companiesProcessed": 51, "emailsFound": 137 }, "errorMessage": null, "createdAt": "2026-07-10T12:00:00.000Z", "updatedAt": "2026-07-10T12:15:00.000Z", "completedAt": null } ``` # Leads Source: https://developer.mailbeast.ai/leads Add, read, update and bulk-manage a campaign's leads. Leads live under a campaign. Add them, sync their state to your CRM, and manage them in bulk. ## Scopes | Action | Scope | | - | - | | List / get / search leads | `leads:read` | | Add / update / delete / bulk-mutate | `leads:write` | ## Add leads Add 1-100 leads in one call. Each is **deduplicated by email** within the campaign and provider-detected. The response summarizes the outcome and returns the leads that were created. ```bash theme={null} curl -X POST https://api.mailbeast.ai/v1/campaigns/{cid}/leads \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "leads": [ { "email": "jane@acme.com", "firstName": "Jane", "companyName": "Acme", "tags": ["vip"], "customFields": { "industry": "SaaS" } }, { "email": "sam@globex.com", "firstName": "Sam" } ] }' ``` ```json Response theme={null} { "summary": { "submitted": 2, "created": 2, "duplicates": 0, "invalid": 0 }, "leads": [ { "id": "…", "email": "jane@acme.com", "status": "not_contacted", "…": "…" } ] } ``` ## List and filter **Cursor-paginated**, newest-first, and stable under concurrent inserts/deletes - the right shape for syncing leads to a CRM (offset pages would skip or duplicate rows as leads change). ```bash theme={null} # first page curl "https://api.mailbeast.ai/v1/campaigns/{cid}/leads?limit=50&status=lead_replied_interested" \ -H "Authorization: Bearer $MAILBEAST_API_KEY" # next page - pass the previous response's meta.nextCursor curl "https://api.mailbeast.ai/v1/campaigns/{cid}/leads?limit=50&cursor=eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0" \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` ```json Response theme={null} { "data": [ { "id": "…", "email": "jane@acme.com", "…": "…" } ], "meta": { "hasMore": true, "nextCursor": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0" } } ``` Filter by `status`, `tags`, `search` (email / name / company), or `engagement`. Keep requesting with `?cursor=meta.nextCursor` until `meta.hasMore` is `false` (then `nextCursor` is `null`). `limit` defaults to 50 (max 250). ### Engagement Every lead carries its engagement, counted **once per email**: | Field | Meaning | | - | - | | `metrics.sent` | Emails that left our servers for the lead (bounced ones included). | | `metrics.opened` | Emails the lead opened. | | `metrics.clicked` | Emails in which the lead clicked a tracked link. | | `lastOpenedAt` / `lastClickedAt` | Latest of the per-email first opens / first clicks: when the lead first opened (clicked in) the newest email it opened (clicked). Re-opens and repeat clicks don't move it; `null` when there is none. | Automated opens and clicks by security scanners and link prefetchers are excluded. Opens are approximate by nature: Apple Mail and some security gateways load images on their own, while clients that block images can hide opens. `?engagement=` narrows the list: | Value | Leads who… | | - | - | | `opened` | opened at least one email | | `opened_no_reply` | opened, and have not replied. Any reply counts, including out-of-office and other auto-replies. | | `clicked` | clicked a tracked link | | `not_opened` | were sent at least one email with open tracking and opened none | ```bash theme={null} curl "https://api.mailbeast.ai/v1/campaigns/{cid}/leads?engagement=opened_no_reply" \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` > [!NOTE] > > Engagement reaches the lead within about a minute of the open or click. ## Get one lead Returns the lead plus **live sequence progress** (steps sent/planned, next send). ```bash theme={null} curl https://api.mailbeast.ai/v1/campaigns/{cid}/leads/{leadId} \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` ## Update a lead ```bash theme={null} curl -X PATCH https://api.mailbeast.ai/v1/campaigns/{cid}/leads/{leadId} \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Janet", "customFields": { "tier": "gold" } }' ``` > [!NOTE] > > Changing a lead's **email** safely re-runs the add / dedup / provider-detect > pipeline, and is only allowed while the lead has not been contacted. ## Bulk mutate One operation over an id list - `set_status`, `add_tags`, `remove_tags`, or `delete`. `delete` also accepts a `filter` instead of ids. ```bash theme={null} # add a tag to specific leads curl -X POST https://api.mailbeast.ai/v1/campaigns/{cid}/leads/mutate \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "operation": "add_tags", "ids": ["…", "…"], "tags": ["hot"] }' # delete every lead matching a filter curl -X POST https://api.mailbeast.ai/v1/campaigns/{cid}/leads/mutate \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "operation": "delete", "filter": { "status": "lead_replied_unsubscribed" } }' # delete EVERY lead - explicit opt-in (an empty filter will NOT do this) curl -X POST https://api.mailbeast.ai/v1/campaigns/{cid}/leads/mutate \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "operation": "delete", "all": true }' ``` ## Search across campaigns Find a lead by email across every campaign in the workspace - one row per campaign the email appears in. ```bash theme={null} curl "https://api.mailbeast.ai/v1/leads/search?email=jane@acme.com" \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` # MCP server Source: https://developer.mailbeast.ai/mcp-server Connect Claude, ChatGPT, Cursor and other AI assistants to your MailBeast workspace. The MailBeast MCP server lets an AI assistant work in your workspace: build and launch campaigns, add leads, check mailboxes and warmup, read and answer replies, and pull analytics - by asking in plain language. ``` https://mcp.mailbeast.ai/mcp ``` Add this URL to your AI app and sign in with your MailBeast account. You choose the workspace and what the assistant may do; no API key to copy. ## Requirements * A MailBeast workspace on the **Pro+** plan (or an enterprise plan with API access) - the same access as the [REST API](/authentication). * You are an **owner or admin** of that workspace. Other roles can't connect apps. * To send email (campaigns, replies, test emails): at least one connected sending mailbox. * An AI app that supports remote MCP servers: Claude (web, desktop, mobile, Claude Code), ChatGPT, Cursor, or any other MCP client that speaks Streamable HTTP and OAuth. ## How connecting works **1. Add the server** Add `https://mcp.mailbeast.ai/mcp` in your AI app (per-app steps below). **2. Sign in** The app opens a MailBeast page in your browser. Sign in if you aren't already. **3. Choose workspace and permissions** Pick the workspace, then the permissions: viewing campaigns, leads, mailboxes, inbox and analytics is always included, and **Make changes and send email** is on by default - switch it off if the assistant should only view. The page shows which app is asking and where you will be sent back. **4. Allow access** Select **Allow access**. You return to the app and the MailBeast tools are ready. Behind the scenes this is standard OAuth 2.1 with PKCE: the app discovers our sign-in from the server's `401` response and its [metadata](https://mcp.mailbeast.ai/.well-known/oauth-protected-resource/mcp). Each approved connection appears as an API key named **"\Hi {{first_name}}, great to hear from you! Pick any time here: [calendar link]
" }, { "subject": "", "body": "Just making sure my last note did not get buried.
", "delayDays": 2 } ] }' ``` A new subsequence is **off** (`"enabled": false`, `status: "draft"`) - it sends nothing until you [turn it on](#turn-on-pause-resume). Name, settings and emails are all-or-nothing: if any part is invalid (`400`; `details` names the field when the error is about one), nothing is created. The response is the subsequence, the same shape as `GET /v1/subsequences/{id}`. ## Settings `settings` has three sections. Each one you send **replaces** that section as a whole; the sections you leave out keep their value (on create: the defaults). ### Trigger - who enters ```json theme={null} "trigger": { "any": [ { "kind": "replied" } ], "sources": ["main"], "filters": [ { "kind": "tag", "op": "has_none", "values": ["competitor"] } ] } ``` `any` holds up to 5 rules - **any** of them enrolls a lead; each kind can be used once. `"any": []` means *manual only*: leads enter only when you [move them in](#move-leads-in). | `kind` | A lead enters when | Extra fields | | - | - | - | | `lead_status` | its status becomes one of `statuses` (from the AI reply classification or set by you) | `statuses`: `lead_replied_interested`, `lead_replied_meeting_request`, `lead_replied_out_of_office`, `lead_replied_wrong_person`, `lead_replied_not_interested`, `lead_replied_uncategorized`, `lead_converted`, `lead_lost` | | `replied` | it replies | - | | `reply_contains` | its reply contains one of `phrases` (case-insensitive) | `phrases`: 1-20 phrases, 2-100 characters each | | `opened` | it opens an email (needs open tracking on the campaign) | `when` | | `clicked` | it clicks a link (needs click tracking) | `when`, optional `urlContains` - only links whose URL contains this text | | `sequence_finished_no_reply` | it got every email of the main sequence and did not reply within `waitDays` | `waitDays`: 0-60 | `when` decides what an open or a click does: * `{ "mode": "after_main_sequence", "waitDays": 0 }` (recommended) - the lead finishes the main sequence first; if it did not reply, it enters `waitDays` later. * `{ "mode": "right_away" }` - it enters at the open or click, and the rest of its main sequence is canceled. `sequence_finished_no_reply` and `"after_main_sequence"` rules watch the main sequence, so they need `"main"` in `sources` (`400` otherwise). `sources` says where the rules listen: `"main"` (the campaign's own sequence) and/or ids of **other subsequences of the same campaign**. That chains flows: a "Re-engage" subsequence can hand leads that reply "Interested" to a "Book a call" one. `trigger` always carries `any`, `sources` and `filters` - pass `[]` when there is nothing to list. `filters` (up to 5) are extra conditions - a lead enters only if **all** match: | `kind` | Fields | | - | - | | `tag` | `op`: `has_any` / `has_none`, `values`: tag names | | `custom_field` | `field`, `op`: `equals` / `contains` / `is_empty` / `is_not_empty`, `value` (for `equals` / `contains`) | | `email_provider` | `values`: `google` / `microsoft` / `other` | | `engagement` | `op`: `opened_at_least` (with `emails`) / `not_opened` / `clicked` / `not_clicked` | | `replied` | `value`: `true` / `false` | | `reached_step` | `atLeast`: step number of the main sequence | Filters are checked when a rule enrolls a lead, not when you move one in, so a manual-only subsequence ignores them. A filter no lead entering by the rules could pass is rejected (`400`): `replied: false` when every rule fires on a reply (`replied`, `reply_contains`, `lead_status` with reply statuses - and Converted - only), `replied: true` when every rule fires only without a reply (`sequence_finished_no_reply`, opens and clicks `"after_main_sequence"`), `engagement` `not_opened` when every rule is an open or a click (a click counts as an open), `not_clicked` when every rule is a click, and `reached_step` past the last step of the main sequence. Two filters of the same kind (`replied`, `email_provider`, `reached_step`) and filters that rule each other out are rejected too. When one event matches several subsequences, the lead enters the first by `position` (set it with `PATCH`). ### Start - when the first email goes out | `start` | First email | | - | - | | `{ "mode": "immediately" }` (default) | at the next sending window | | `{ "mode": "delay", "amount": 2, "unit": "days" }` | after the delay (`minutes` / `hours` / `days`, up to 365 days) | | `{ "mode": "ooo_return", "offsetDays": 1, "withoutDate": { "mode": "delay", "days": 7 }, "maxDaysAhead": 120 }` | `offsetDays` after the return date found in the out-of-office reply; without a date, `days` after the auto-reply (or `{ "mode": "skip" }`); a lead away longer than `maxDaysAhead` days is skipped (`null` = no limit) | `ooo_return` works only with a single `lead_status` rule for `lead_replied_out_of_office`. The first step has no delay of its own - `start` is it. Emails still go out only inside the sending schedule. ### Sending ```json theme={null} "sending": { "schedule": "inherit", "dailyLimit": { "mode": "inherit" } } ``` * `schedule`: `inherit` - the campaign's schedule (default); `custom` - the subsequence keeps its own schedule, edited in the dashboard. * `dailyLimit.mode`: `inherit` - its emails count toward the campaign's daily limit and go out first, the campaign's own emails use the rest (default); `custom` - its own limit `value` on top of the campaign's; `unlimited` - only the mailboxes' own daily limits apply. Whether a subsequence is on is **not** a setting: `settings.enabled` in a request is a `400`. Use `/enable` and `/pause`. ## Emails `sequence` follows the same rules as a campaign's sequence: a step is `subject` + `body` (one variant A) or `variants` (an A/B test, up to 5, leads split evenly). Two differences: * **An empty subject (`""`) replies in the same thread** as the conversation with the lead - recommended for the first step. A subject of its own starts a new thread. * **Step 1 has no delay** - `delayDays` / `delayHours` must be `0` or left out on it (`400` otherwise); when it goes out is set by `settings.start`. Later steps wait `delayDays` / `delayHours` after the previous one - at least 1 hour (`400` otherwise, nothing is created). ## Turn on, pause, resume ```bash theme={null} curl -X POST https://api.mailbeast.ai/v1/subsequences/{id}/enable \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "enrollExisting": true }' ``` ```json Response theme={null} { "id": "5b2f3c4d-…", "status": "active", "enabled": true, "state": "active", "enrollingExisting": true, "success": true } ``` * `/enable` turns it on: from now on, leads that match the trigger enter it. `enrollExisting: true` also enrolls the leads that **already** match (in the background) - by a lead status, a reply, a finished main sequence, or an open / a click in the main sequence; `reply_contains` rules and clicks on a URL count only from now on. A lead going through another subsequence right now is not taken out of it. On a **draft** campaign the subsequence stays `draft` while on and starts together with the campaign. * `/pause` turns it off: no new leads enter, and leads already in it wait - nothing more is sent to them - until it is resumed. The main sequence keeps sending. If this was the campaign's last subsequence that is on, the main sequence has finished and no lead is still in a subsequence, the campaign then completes on its own (unless it keeps active when leads run out) - and `/enable` needs a restart in the dashboard. * `/resume` is the same as `/enable`: waiting leads continue, new ones enter again. A subsequence needs at least one email to be turned on (`400`). On a **completed** campaign `/enable` answers `409 parent_completed` - restart the campaign in the dashboard first. A deleted campaign answers `404`. `state` says in one word why a subsequence is (not) sending: | `state` | Meaning | | - | - | | `draft` | off | | `starts_with_campaign` | on, starts when the draft campaign starts | | `active` | on and sending | | `paused` | paused by you | | `paused_with_campaign` | on, but the campaign is paused - nothing is sent until it resumes | | `stopped_campaign_ended` | the campaign completed, was stopped or deleted | | `paused_requires_plan` | the plan does not include subsequences | | `cant_start` | on, but it cannot start: it has no email, or an email is missing content | | `waiting_restart` | on, waiting for the completed campaign to be restarted | `status` is the subsequence's campaign status: `active` = sending; `draft` / `paused` = not sending right now - it can still be on and wait for the campaign to start or restart; `enabled` and `state` tell which. ## Move leads in Move leads of the campaign into a subsequence by hand - by lead id or by email, up to 1000 per call: ```bash theme={null} curl -X POST https://api.mailbeast.ai/v1/subsequences/{id}/leads \ -H "Authorization: Bearer $MAILBEAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "emails": ["jane@acme.com", "sam@globex.com"], "start": { "mode": "delay", "days": 2 } }' ``` ```json Response theme={null} { "enrolled": 1, "skipped": { "not_contacted": 1 }, "notFound": 0 } ``` Pass `leadIds` (ids of the **campaign's** leads, from `GET /v1/campaigns/{id}/leads`) or `emails`, not both. `start` is `{ "mode": "now" }` (the default), `{ "mode": "delay", "days": N }` or `{ "mode": "date", "date": "YYYY-MM-DD" }` - it overrides the subsequence's own `settings.start` for these leads. Moving works whether the subsequence is on or off: into one that is paused or was never turned on, the leads wait and start when you `/enable` (or `/resume`) it. Each lead's remaining campaign emails are canceled, exactly as when a trigger fires. The response counts who entered, who did not and why, and which ids or emails are not leads of the campaign (`notFound`): | `skipped` reason | Why | | - | - | | `not_contacted` | the lead was never emailed - a subsequence continues a conversation | | `already_enrolled` | the lead was in this subsequence before - each lead enters once | | `suppressed` | unsubscribed, bounced or blacklisted | | `company_replied` | a colleague at the same company replied in this campaign or one of its subsequences, and the campaign stops the company on a reply | | `lead_removed` | the lead was removed from the campaign | | `not_accepting` | the campaign is not active or paused (draft, completed, stopped or deleted), the subsequence is completed or deleted, or your plan does not include subsequences. A subsequence that is paused or was never turned on still takes leads | | `thread_unavailable` | step 1 replies in the same thread (empty subject), but the conversation's thread could not be found - give step 1 a subject of its own | Treat any other key in `skipped` the same way - the lead did not enter (for example, `not_family_lead` when the lead was removed from the campaign while the call ran). ## Read ```bash theme={null} # all subsequences of a campaign, in position order curl https://api.mailbeast.ai/v1/campaigns/{campaignId}/subsequences \ -H "Authorization: Bearer $MAILBEAST_API_KEY" # one subsequence curl https://api.mailbeast.ai/v1/subsequences/{id} \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` The list answers `{ "data": [ … ] }` - an array of subsequences; one subsequence is the object itself: ```json Response theme={null} { "id": "5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c", "campaignId": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "name": "Interested - book a call", "position": 1, "status": "active", "enabled": true, "state": "active", "settings": { "trigger": { "any": [ { "kind": "lead_status", "statuses": ["lead_replied_interested"] } ], "sources": ["main"], "filters": [] }, "start": { "mode": "delay", "amount": 1, "unit": "hours" }, "sending": { "schedule": "inherit", "dailyLimit": { "mode": "inherit" } } }, "sequence": [ { "id": "9a8b7c6d-…", "subject": "", "body": "Hi {{first_name}}, …
", "delayDays": 0, "delayHours": 0, "variants": [ { "id": "550e8400-…", "label": "A", "subject": "", "body": "…
", "isActive": true } ] } ], "counters": { "entered": 42, "waiting": 3, "inProgress": 12, "replied": 9, "positive": 5, "ended": 30 }, "nextStartAt": "2026-10-29T09:00:00.000Z", "createdAt": "2026-10-28T08:00:00.000Z" } ``` `entered = inProgress + ended`: an entry ends when its emails are all sent, the lead replies, its status changes, it is removed or moves to another subsequence. `waiting` (part of `inProgress`) is leads whose first email is not due yet. `positive` counts leads that replied and whose status is positive now, when the lead became positive during this subsequence - a subset of `replied`. A lead that turned positive in the main sequence counts there, not here. The campaign lists its subsequences too - `GET /v1/campaigns/{id}` has `"subsequences": [{ "id", "name", "status" }]`, and `GET /v1/campaigns/{id}/analytics` adds `subsequences` with entered / in progress / replied / positive counters per subsequence (all time). The campaign's analytics `totals` cover the campaign with its subsequences by default; `scope=main` gives the main sequence and `subsequenceId={id}` one subsequence (see [Analytics](/analytics)). > [!NOTE] > > A subsequence id is **not** a campaign id in the API: it does not appear in > `GET /v1/campaigns`, and every `/v1/campaigns/{id}…` route answers `404` for it > (`/v1/leads/search` does not return subsequence lead rows either - it returns the > lead's row in the campaign). Use `/v1/subsequences/{id}`. > > Emails of a subsequence in [`/v1/emails`](/emails) come with > the **main campaign's** `campaignId` and the lead's id in that campaign, plus a > `subsequence` object (`id`, `name`) - so every id you receive works with > `/v1/campaigns/{id}…`. ## Update and delete `PATCH /v1/subsequences/{id}` changes only what you send: `name`, `position`, any `settings` section, `sequence`. A sent section or `sequence` replaces the current one; step and variant ids change when `sequence` is replaced. The emails of a running subsequence cannot be replaced - pause it first (`400`, nothing is written; see [`/pause`](#turn-on-pause-resume) for what turning off the last subsequence that is on does). Sections are written one after another, as with `PATCH /v1/campaigns/{id}`. `DELETE /v1/subsequences/{id}` deletes it: its scheduled emails are canceled, and leads in it do not return to the main sequence. Deleting the campaign's last subsequence that is on can let a campaign whose main sequence has finished complete, as `/pause` does. ## Errors Errors use the usual envelope. Codes specific to subsequences: | Status | `code` | Meaning | | - | - | - | | `400` | `validation_failed` | invalid settings or emails - `details` names the field when there is one, e.g. `settings.trigger.sources: …`; other checks (a loop of sources, a source from another campaign) explain it in `message` | | `403` | `subsequences_plan_required` | the plan does not include subsequences | | `404` | `not_found` | no such subsequence in your workspace (or a campaign id was used) | | `409` | `campaign_busy` | the campaign is being changed right now - retry in a few seconds (`Retry-After` is set) | | `409` | `campaign_state_changed` | the campaign changed (paused, completed, deleted) while the request ran - read it again | | `409` | `parent_completed` | `/enable` on a completed campaign - restart it in the dashboard first | | `409` | `family_ended` | the campaign ended (stopped, or deleted while the request ran) | | `409` | `subsequence_limit_reached` | the campaign already has as many subsequences as it can - delete one to add another | ## MCP The [MCP server](/mcp-server) has `list_subsequences`, `create_subsequence`, `update_subsequence` and `enroll_in_subsequence`. A subsequence created there is off; it is turned on in the [dashboard](https://app.mailbeast.ai) or with `POST /v1/subsequences/{id}/enable`. # Workspace & Usage Source: https://developer.mailbeast.ai/workspace Read your limits, subscription, and plan - know what's left before you hit a limit. These endpoints let you read your own limits, subscription, and plan. They're all read-only. Use them to see how much you have left **before** a request would hit a plan limit (`402`) or the rate limit (`429`) - so nothing catches you off guard. ## Scopes | Action | Scope | | - | - | | Read usage, subscription, and workspace | `usage:read` | ## Check your usage before you spend `GET /v1/usage` returns how much you've used and have left, grouped by product. Email Outreach and Lead Finder are separate products, so each is reported on its own - your Email Outreach plan limits and your Lead Finder credit balance. ```bash theme={null} curl https://api.mailbeast.ai/v1/usage \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` ```json theme={null} { "emailOutreach": { "planName": "pro", "limits": [ { "limitType": "monthly_emails", "used": 1240, "limit": 100000, "remaining": 98760, "isUnlimited": false, "usagePercentage": 1.24 }, { "limitType": "active_contacts", "used": 5000, "limit": 25000, "remaining": 20000, "isUnlimited": false, "usagePercentage": 20 } ] }, "leadFinder": { "credits": { "limitType": "lead_finder_credits", "used": 0, "limit": 500, "remaining": 500, "isUnlimited": false, "usagePercentage": 0 } } } ``` > [!TIP] > > Before a large lead import or a send, read the relevant limit and only proceed > while `remaining` is comfortable. This turns a `402` from a surprise into a > decision you control. ## Subscription: everything you pay for, in one place `GET /v1/account/subscription` groups your billing by product. **Email Outreach** and **Lead Finder** are independent subscriptions, each with its own billing cycle and renewal date. ```bash theme={null} curl https://api.mailbeast.ai/v1/account/subscription \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` ```json theme={null} { "emailOutreach": { "planName": "pro", "status": "active", "billingInterval": "monthly", "currentPeriodEnd": "2026-08-01T00:00:00.000Z", "cancelAtPeriodEnd": false, "trial": null, "addons": { "contacts": 20000, "monthlyEmails": 10000, "aiCredits": 5000, "emailValidation": 0 } }, "leadFinder": { "tier": "pro", "status": "active", "billingInterval": "annual", "currentPeriodEnd": "2027-02-01T00:00:00.000Z", "cancelAtPeriodEnd": false } } ``` * **Your Email Outreach status** - `active`, `on_hold`, or `inactive` when you have no active subscription (for example, on the free plan). * **`currentPeriodEnd`** - when each product's current paid period ends. It renews then, or ends if `cancelAtPeriodEnd` is `true`, and is `null` when there's no active subscription. Each product has its own, so they can differ. * **Your Email Outreach add-ons** - the extra capacity you've purchased, in units. They're already folded into the caps in `GET /v1/usage`, so this is just the breakdown. `null` when you have no add-ons, and while the plan is on hold, since the extra capacity isn't active then either. * **Your Lead Finder subscription** - billed separately from Email Outreach. `null` if you don't have one. The Lead Finder credit balance itself lives in `GET /v1/usage` under `leadFinder.credits`. ## Workspace identity `GET /v1/workspace` returns the workspace resolved from your key: org name and timezone. Your plan lives in [`GET /v1/usage`](#check-your-usage-before-you-spend) and [`GET /v1/account/subscription`](#subscription-everything-you-pay-for-in-one-place). ```bash theme={null} curl https://api.mailbeast.ai/v1/workspace \ -H "Authorization: Bearer $MAILBEAST_API_KEY" ``` ```json theme={null} { "organizationId": "…", "name": "Acme Inc", "timezone": "America/New_York" } ```