# MailBeast API

> Task-shaped REST API for cold email at scale - campaigns, leads, deliverability, verification and lead discovery.

## Docs

- [Overview](https://developer.mailbeast.ai/introduction.md): One API for the full local lead-gen & cold-outreach loop.
- [Quickstart](https://developer.mailbeast.ai/quickstart.md): From zero to your first authenticated call in two steps.
- [Authentication](https://developer.mailbeast.ai/authentication.md): API keys, scopes, and how the workspace is resolved.
- [Idempotency](https://developer.mailbeast.ai/idempotency.md): Retry writes safely - 24h response replay, plus durable dedup for quota and leads.
- [Lead Finder](https://developer.mailbeast.ai/lead-finder.md): List past lead searches and poll a running search's progress.
- [Email Accounts](https://developer.mailbeast.ai/accounts.md): Connect and manage the sending mailboxes your campaigns send from.
- [Campaigns](https://developer.mailbeast.ai/campaigns.md): Create, configure, launch and monitor email campaigns.
- [Emails](https://developer.mailbeast.ai/emails.md): Read the replies your campaigns get, and answer them.
- [Leads](https://developer.mailbeast.ai/leads.md): Add, read, update and bulk-manage a campaign's leads.
- [Workspace & Usage](https://developer.mailbeast.ai/workspace.md): Read your limits, subscription, and plan - know what's left before you hit a limit.
- [Analytics](https://developer.mailbeast.ai/analytics.md): Engagement reporting – per campaign, over time, and across the workspace.
- [List lead searches](https://developer.mailbeast.ai/api-reference/lead-finder/list-lead-searches.md): Cursor-paginate the workspace’s lead searches (newest-first, stable under concurrent changes) for history and to discover ids to poll. In-progress chat drafts are not listed.
- [Get a lead search](https://developer.mailbeast.ai/api-reference/lead-finder/get-a-lead-search.md): One search’s status and live progress counters (companies found, companies processed, emails found) – the single target to poll while a run is in flight.
- [Connect mailboxes](https://developer.mailbeast.ai/api-reference/email-accounts/connect-mailboxes.md): Connect one SMTP/IMAP mailbox, or up to 50 at once. Any provider works, including Gmail and Outlook with an app password. There is no limit on how many mailboxes a workspace may connect.
- [List mailboxes](https://developer.mailbeast.ai/api-reference/email-accounts/list-mailboxes.md): List your mailboxes, newest first, with stable cursor pagination. Filter by `status` or `tags` (any-of), or pass `email` to look one mailbox up by its address instead of by `id`.
- [Get a mailbox](https://developer.mailbeast.ai/api-reference/email-accounts/get-a-mailbox.md): Fetch one mailbox with its embedded status, health score, and verification snapshot.
- [Update a mailbox](https://developer.mailbeast.ai/api-reference/email-accounts/update-a-mailbox.md): Update a mailbox’s settings and limits, and rotate its SMTP/IMAP credentials. The email address cannot be changed. Including any `smtp*` or `imap*` field rotates the credentials and re-runs verification.
- [Delete a mailbox](https://developer.mailbeast.ai/api-reference/email-accounts/delete-a-mailbox.md): Delete a mailbox from your workspace. Sending from it stops immediately.
- [Bulk update mailboxes](https://developer.mailbeast.ai/api-reference/email-accounts/bulk-update-mailboxes.md): Apply ONE settings/limits `patch` OR one `status` change (`active`/`inactive`) across many mailboxes. `patch` and `status` are mutually exclusive.
- [Verification result](https://developer.mailbeast.ai/api-reference/email-accounts/verification-result.md): The latest SMTP + IMAP + DNS verification result for a mailbox.
- [Pause a mailbox](https://developer.mailbeast.ai/api-reference/email-accounts/pause-a-mailbox.md): Stop sending from an active mailbox. It stays paused until you `resume` it - campaigns and warmup both skip it, and nothing re-activates it on its own. Returns `400` if the mailbox is not currently active.
- [Resume a mailbox](https://developer.mailbeast.ai/api-reference/email-accounts/resume-a-mailbox.md): Start sending from a mailbox again. One you paused resumes immediately; one we stopped after repeated failures is re-verified first and only resumes if the check passes.
- [Start OAuth connect](https://developer.mailbeast.ai/api-reference/email-accounts/start-oauth-connect.md): Start connecting a Google Workspace or Microsoft mailbox over OAuth. Returns a consent URL to open in a browser, plus a `state` handle. Once the owner grants access, poll `GET /v1/accounts/oauth/{provider}/status?state=…`.
- [Poll OAuth connect](https://developer.mailbeast.ai/api-reference/email-accounts/poll-oauth-connect.md): Poll a connect started with `init`. `pending` until the mailbox owner finishes consent, then `connected` (with `accountId`) or `failed`.
- [Create a campaign](https://developer.mailbeast.ai/api-reference/campaigns/create-a-campaign.md): Create a campaign with its schedule, settings, sequence, sending accounts, and optionally its leads, in one call. Set `launch: true` to start it right away, which also needs the `campaigns:lifecycle` scope. If it cannot launch, the campaign is still created and `launchError` says why.
- [Start campaign](https://developer.mailbeast.ai/api-reference/campaigns/start-campaign.md): Begin sending (or resume a paused campaign). Needs a lead list and a sequence - returns 400 if the campaign has nothing to send.
- [Pause campaign](https://developer.mailbeast.ai/api-reference/campaigns/pause-campaign.md): Pause an active campaign. In-flight sends finish; nothing new is scheduled.
- [Resume campaign](https://developer.mailbeast.ai/api-reference/campaigns/resume-campaign.md): Resume a paused campaign from where it left off.
- [Send a test email](https://developer.mailbeast.ai/api-reference/campaigns/send-a-test-email.md): Send yourself a rendered preview of one step variant before launching. It goes from a real mailbox and counts toward that mailbox's daily limit, but not your monthly quota. Capped at 12 per day per workspace.
- [List campaigns](https://developer.mailbeast.ai/api-reference/campaigns/list-campaigns.md): Cursor-paginate the workspace campaigns (id, name, status, lead count), newest-first and stable under concurrent changes.
- [Get a campaign](https://developer.mailbeast.ai/api-reference/campaigns/get-a-campaign.md): Full config - schedule, settings, sequence steps, attached accounts, headline metrics.
- [Update a campaign](https://developer.mailbeast.ai/api-reference/campaigns/update-a-campaign.md): Partial update - only the supplied sections are touched. `accounts` and `sequence`, when present, REPLACE the existing set.
- [Delete a campaign](https://developer.mailbeast.ai/api-reference/campaigns/delete-a-campaign.md): Delete a campaign to clean up programmatically-created resources.
- [Campaign send status](https://developer.mailbeast.ai/api-reference/campaigns/campaign-send-status.md): Lightweight live send-state (running/paused/completed), schedule-window state, and headline metrics. Deep reporting lives under the analytics endpoints.
- [List emails](https://developer.mailbeast.ai/api-reference/emails/list-emails.md): List emails across your mailboxes, newest first. Results carry a `snippet` preview but never the message body; fetch a single email to read it. Filter by mailbox, campaign, conversation, lead, read state, direction, folder, date, or full-text search.
- [Get an email](https://developer.mailbeast.ai/api-reference/emails/get-an-email.md): Fetch one email with its body – the only endpoint that returns the body. A `null` body means none was stored; if the stored body can't be read right now the call returns `503` rather than a false empty.
- [Delete an email](https://developer.mailbeast.ai/api-reference/emails/delete-an-email.md): Remove an email from your inbox. It stops appearing in listings. The copy on the mail server is not touched.
- [Reply to an email](https://developer.mailbeast.ai/api-reference/emails/reply-to-an-email.md): Reply within the email's conversation. It is sent from the mailbox that owns the thread to the other party – you supply only the body (plus optional cc/bcc, which are blocklist-checked).
- [Forward an email](https://developer.mailbeast.ai/api-reference/emails/forward-an-email.md): Forward an email to recipients you choose. It is sent from the mailbox that owns the thread, with the original quoted below your note; all recipients are blocklist-checked.
- [Count unread emails](https://developer.mailbeast.ai/api-reference/emails/count-unread-emails.md): Number of unread emails, optionally narrowed to specific mailboxes or a campaign. Emails outside a conversation have no read state and are not counted.
- [Mark a conversation read](https://developer.mailbeast.ai/api-reference/emails/mark-a-conversation-read.md): Mark every email in a conversation as read in one call. Read state lives on the conversation, not the individual email - this is the one call that clears it.
- [Add leads](https://developer.mailbeast.ai/api-reference/leads/add-leads.md): Add 1-100 leads to a campaign. Each is deduplicated by email within the campaign, provider-detected, and counts toward the monthly-imports quota. The response summarizes the outcome and returns the created leads.
- [List campaign leads](https://developer.mailbeast.ai/api-reference/leads/list-campaign-leads.md): Page through a campaign’s leads with filters (status, tags, search).
- [Get a lead](https://developer.mailbeast.ai/api-reference/leads/get-a-lead.md): One lead including live sequence progress (steps sent/planned, next send).
- [Update a lead](https://developer.mailbeast.ai/api-reference/leads/update-a-lead.md): Update a lead’s fields, tags, custom fields, or status. The email address can only be changed while the lead has not been contacted yet. Reply-based statuses can only be set once the lead has replied.
- [Delete a lead](https://developer.mailbeast.ai/api-reference/leads/delete-a-lead.md): Remove a single lead. Contacted leads are soft-deleted with a retention window.
- [Bulk mutate leads](https://developer.mailbeast.ai/api-reference/leads/bulk-mutate-leads.md): Apply one operation (`set_status`, `add_tags`, `remove_tags`, or `delete`) across many leads. Target them by `ids`; `delete` also accepts a `filter`, or `all: true` to remove every lead. Reply-based statuses can only be set on leads that have already replied.
- [Search leads by email](https://developer.mailbeast.ai/api-reference/leads/search-leads-by-email.md): Find leads across all of the workspace’s campaigns by email (or fragment), for dedupe and cross-campaign lookup. Returns up to 10 matches.
- [Create an API key](https://developer.mailbeast.ai/api-reference/api-keys/create-an-api-key.md): Mint a new key for your workspace. The full token is returned **once**, so store it immediately. Requested scopes must be a subset of the calling key’s own scopes, and cannot include `apikeys:manage`.
- [List API keys](https://developer.mailbeast.ai/api-reference/api-keys/list-api-keys.md): All keys in the caller’s workspace, with masked prefixes (no secrets).
- [Revoke an API key](https://developer.mailbeast.ai/api-reference/api-keys/revoke-an-api-key.md): Revoke a key by id - effective immediately. Cannot be undone.
- [Current usage](https://developer.mailbeast.ai/api-reference/workspace/current-usage.md): Everything you have used and everything you have left, grouped by product: your Email Outreach plan limits and your Lead Finder credits. Check it before a large send or import. For billing cycles and renewal dates, see `GET /v1/account/subscription`.
- [Current usage for one limit](https://developer.mailbeast.ai/api-reference/workspace/current-usage-for-one-limit.md): Just one limit (used/limit/remaining/percentage/isUnlimited) - handy when you only care about the one you’re about to spend.
- [Subscription](https://developer.mailbeast.ai/api-reference/workspace/subscription.md): Everything you pay for, grouped by product: your Email Outreach subscription and your separate Lead Finder subscription. Each has its own plan, status, and billing cycle.
- [Workspace identity](https://developer.mailbeast.ai/api-reference/workspace/workspace-identity.md): Who this key belongs to - your workspace name and timezone. (Your plan lives in `GET /v1/usage` and `GET /v1/account/subscription`.)
- [Campaign analytics](https://developer.mailbeast.ai/api-reference/analytics/campaign-analytics.md): Aggregate engagement for one campaign. Ask for extra breakdowns with `breakdown=smtp,sequence,bounce` – each is an extra query, so request only what you will read.
- [Campaign analytics over time](https://developer.mailbeast.ai/api-reference/analytics/campaign-analytics-over-time.md): One point per interval so you can chart a campaign – this series carries bounces AND unsubscribes, so those rates are chartable without extra calls. Long windows auto-coarsen (day → week → month); the response says which interval it used.
- [Workspace analytics roll-up](https://developer.mailbeast.ai/api-reference/analytics/workspace-analytics-roll-up.md): Engagement rolled up across every campaign in the workspace, plus the highest-volume campaigns. Use it for a top-level dashboard; drill into a campaign for detail.

## OpenAPI Specs

- [openapi](https://developer.mailbeast.ai/openapi.json)