",
"mailbox": { "id": "3f1c2b7e-9a4d-4c8e-b1f6-5d2a7e0c3b94", "email": "jane@acme.com" },
"from": { "email": "john@prospect.io", "name": "John Carter" },
"to": ["jane@acme.com"],
"cc": [],
"bcc": [],
"subject": "Re: Pricing question",
"snippet": "Thanks for the details, this works for us.",
"isUnread": true,
"type": "received",
"campaignId": "c1f3b0a2-6d4e-4f8b-9a1c-2e5d7f0a3b6c",
"leadId": "9d4e2f10-5b6a-4c73-8e19-0f2a7c4d8b31",
"hasAttachments": false,
"receivedAt": "2026-07-13T09:24:11.000Z",
"sentAt": null
}
],
"meta": { "hasMore": false, "nextCursor": null }
}
```
Filters combine freely: `mailbox` (comma-separated addresses), `campaignId`,
`threadId`, `leadId`, `isUnread`, `type` (`sent` or `received`),
`folder` (`inbox`, `untracked`, `important`, `snoozed`, or `archived`), `since`,
`until`, and `search`.
`search` is full text over subject, preview text and sender address. Quoted
phrases, `OR` and `-exclude` all work.
### Conversations without fetching them
Pass `latestOfThread=true` to get one email per conversation. That gives you a
conversation-style view at the cost of an ordinary list.
```bash theme={null}
curl -G https://api.mailbeast.ai/v1/emails \
-H "Authorization: Bearer $MAILBEAST_API_KEY" \
-d latestOfThread=true -d limit=25
```
Your other filters are applied **first**, and the newest email that survives them
is the one you get back. So this returns the last message each contact sent you –
including in conversations you have already answered, where the newest message in
the thread is your own reply:
```bash theme={null}
curl -G https://api.mailbeast.ai/v1/emails \
-H "Authorization: Bearer $MAILBEAST_API_KEY" \
-d latestOfThread=true -d type=received
```
An email that belongs to no conversation is a conversation of one, and is always
kept.
To open one conversation, list its messages with `?threadId=...`.
## Read one email
`GET /v1/emails/{id}` is the only endpoint that returns the body.
```bash theme={null}
curl https://api.mailbeast.ai/v1/emails/{id} \
-H "Authorization: Bearer $MAILBEAST_API_KEY"
```
It returns the same object as the list, plus:
```json theme={null}
{
"body": {
"html": "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"
```
## Delete an email
`DELETE /v1/emails/{id}` removes an email from your inbox. It stops appearing in
listings. The copy on the mail server is left alone.
# 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
```
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.
**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 - revoke any extras from the [list endpoint](/api-reference/api-keys/list-api-keys).
## 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` |
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.
`https://api.mailbeast.ai`
`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.
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.
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. Adding leads counts toward your monthly-imports quota.
## 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`, or `search` (email / name / company). Keep requesting
with `?cursor=meta.nextCursor` until `meta.hasMore` is `false` (then `nextCursor`
is `null`). `limit` defaults to 50 (max 250).
## 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" } }'
```
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"
```
# Quickstart
Source: https://developer.mailbeast.ai/quickstart
From zero to your first authenticated call in two steps.
In the dashboard, open [**Settings → API Keys**](https://app.mailbeast.ai/settings/api), click **Create API key**,
include the **`apikeys:manage`** scope (plus any scopes you want to delegate,
e.g. `campaigns:read`), and copy the secret - it is shown only once.
List the keys in your workspace. A `200` with your key in the response
confirms the token and scope are resolved correctly.
```bash theme={null}
curl https://api.mailbeast.ai/v1/api-keys \
-H "Authorization: Bearer $MAILBEAST_API_KEY"
```
```json Response theme={null}
{
"data": [
{
"id": "b6fd2c26-…",
"name": "Bootstrap",
"keyPrefix": "mb_live_7Fq2Ka9Lm3Xb0ZpH_••••",
"scopes": ["apikeys:manage", "campaigns:read"],
"environment": "live",
"lastUsedAt": null,
"expiresAt": null,
"revokedAt": null,
"createdAt": "2026-07-11T09:12:04.000Z"
}
]
}
```
For security reasons, the API key will be displayed only once, and there is no way to recover it if you lose it.
# 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 }
}
}
```
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"
}
```