MailBeast

Run cold email outreach from your AI assistant: launch campaigns with A/B sequences, manage leads and warmed-up sending mailboxes, read and answer replies, and see campaign analytics in MailBeast. OAuth sign-in with read-only or read + write access.

View on mailbeast.ai

Hosted MCP Server

npx add-mcp 'https://mcp.mailbeast.ai/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

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.
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

Add `https://mcp.mailbeast.ai/mcp` in your AI app (per-app steps below). The app opens a MailBeast page in your browser. Sign in if you aren't already. 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. 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. Each approved connection appears as an API key named "<App> (MCP)" - for example "Claude (MCP)" - in Settings → API Keys.

Connect your app

Add it on claude.ai or in Claude Desktop; it then works in the Claude mobile apps too.

1. Open **Customize → Connectors** ([claude.ai/customize/connectors](https://claude.ai/customize/connectors)).
2. Select **Add custom connector**, name it `MailBeast` and enter
   `https://mcp.mailbeast.ai/mcp`. Leave the OAuth client ID and secret empty.
3. Select **Add**, then **Connect**, and approve access in the browser.
4. In a chat, turn MailBeast on under **+ → Connectors**.

On **Team and Enterprise** plans an organization Owner first adds the connector in
**Organization settings → Connectors** (**Add → Custom**, same URL); then each
member opens **Customize → Connectors** and selects **Connect**.

1. Open [chatgpt.com/plugins](https://chatgpt.com/plugins). 2. Select **+**, then **Add custom MCP server**. Name it `MailBeast`. 3. Under **Connection**, enter `https://mcp.mailbeast.ai/mcp` and choose **OAuth** for authentication. 4. Confirm the risk notice and select **Create as a plugin**, then approve access in the browser. 5. In a chat, type `@MailBeast` to use it.

Custom MCP servers in ChatGPT depend on your plan and workspace settings. On
Business, only workspace admins and owners can add them; on Pro, ChatGPT connects
custom servers for reading only. See
[OpenAI's help article](https://help.openai.com/en/articles/12584461).

```bash theme={null} claude mcp add --transport http mailbeast https://mcp.mailbeast.ai/mcp ```

Start Claude Code, run `/mcp`, select **mailbeast** and **Authenticate**. Your
browser opens; approve access and return to the terminal.

Or add it to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json theme={null}
{
  "mcpServers": {
    "MailBeast": {
      "url": "https://mcp.mailbeast.ai/mcp"
    }
  }
}
```

In **Cursor Settings → MCP**, MailBeast shows **Needs login** - select it and
approve access in the browser.

Permissions

You approve	The assistant can	Behind it
View (always included)	Read campaigns, sequences, leads, mailboxes and their health, emails and replies, analytics, Lead Finder searches, plan usage	API key with `all:read`
View + Make changes and send email	Everything above, plus: create, change, start, pause and delete campaigns; add, update and delete leads; change, pause and remove mailboxes; connect Google / Microsoft mailboxes by link; mark conversations read; reply to and forward emails; send test emails	API key with `all:all`

Read-only means read-only: the assistant can't change anything or send email. It still sees the content it reads - your emails, replies and lead data - and passes it to the AI app you use.

Whatever you approve, the assistant can't:

create or see API keys, or change your plan and billing;
see any password - over a sign-in connection it doesn't accept SMTP/IMAP passwords at all (connect those mailboxes in the dashboard);
go beyond your workspace's plan limits and the rate limit - tool calls count against it like direct API requests (120 per minute per workspace).

To change permissions, connect again with the other choice and delete the old "(MCP)" key.

Disconnect

In MailBeast - delete the app's key ("Claude (MCP)", "ChatGPT (MCP)", …) in Settings → API Keys. Access ends immediately: the app's next call is refused and it has to sign in again.
In the app - remove the connector (Claude: Customize → Connectors → … → Remove; ChatGPT: remove the plugin in Plugins; Claude Code: claude mcp remove mailbeast; Cursor and other clients: remove it from the MCP settings or config file).

Removing the connector in the app alone may leave the key in MailBeast - delete it there to revoke access for sure.

Connect with an API key

For scripts, CI, and clients without OAuth sign-in. Create a key in Settings → API Keys - a separate key for MCP, with only the scopes you need (all:read for read-only, all:all for everything) - and send it as a header:

Authorization: Bearer mb_live_…

```bash theme={null} claude mcp add --transport http mailbeast https://mcp.mailbeast.ai/mcp \ --header "Authorization: Bearer $MAILBEAST_API_KEY" ``` ```json theme={null} { "mcpServers": { "MailBeast": { "url": "https://mcp.mailbeast.ai/mcp", "headers": { "Authorization": "Bearer mb_live_…" } } } } ```

The assistant sees only the tools the key's scopes allow. A key connection also offers connect_mailboxes (SMTP/IMAP with passwords) and credential changes in update_mailbox, which sign-in connections don't.

Warning

Never put an API key in the server URL. Older setups that used a URL containing the key keep working for now, but switch them to sign-in or the header above and delete that key - URLs end up in logs, browser history and screenshots.

Tools

Access shows what a tool needs: Read works on every connection; Write needs Make changes and send email; Sends email needs Make changes and send email and sends real email to real recipients. Every tool calls the matching endpoint of the REST API (see the API Reference tab) - the MCP server adds no permissions of its own.

Workspace

Tool	What it does	Access
`get_workspace`	Workspace name and timezone, plan, and usage against every plan limit	Read

Mailboxes

Tool	What it does	Access
`list_mailboxes`	Sending mailboxes with status, health score, warmup and limits	Read
`get_mailbox`	One mailbox: status and why it last failed, warmup, limits; optionally the latest connection test	Read
`start_oauth_connect`	Starts connecting a Google Workspace or Microsoft 365 mailbox: returns a link you open to sign in - no password	Write
`check_oauth_connect`	Checks whether that sign-in finished	Read
`update_mailbox`	Changes sender name, daily cap, sending gap, signature, reply-to, BCC, tracking domain, warmup, language	Write
`pause_mailbox` / `resume_mailbox`	Stops a mailbox from sending / brings it back (a failed one gets a fresh connection test)	Write
`bulk_update_mailboxes`	One change - status or shared settings - for up to 1000 mailboxes	Write
`delete_mailbox`	Removes a mailbox from the workspace	Write
`connect_mailboxes`	Connects SMTP/IMAP mailboxes with passwords - API key connections only	Write

Campaigns

Tool	What it does	Access
`list_campaigns`	Campaigns with status and lead count	Read
`get_campaign`	One campaign: schedule, settings, metrics, mailboxes, every sequence step and A/B variant, whether it's inside its sending window	Read
`create_campaign`	Creates a campaign as a draft (nothing is sent): schedule, settings, sequence with A/B variants, tags, lead emails	Write
`update_campaign`	Changes a campaign; a new sequence, mailbox list or tag list replaces the current one	Write
`send_test_email`	Sends one preview of a sequence step to one address (12 per day per workspace)	Sends email
`start_campaign`	Starts sending a draft campaign to its leads on its schedule	Sends email
`pause_campaign`	Pauses a campaign - nothing more is sent until it's resumed	Write
`resume_campaign`	Resumes a paused campaign - sending continues on its schedule	Sends email
`delete_campaign`	Permanently deletes a campaign and stops its sending	Write

Leads

Tool	What it does	Access
`add_leads`	Adds up to 100 leads per call to a campaign (deduplicated by email)	Write
`list_leads`	A campaign's leads with status and engagement (opened, clicked, replied)	Read
`get_lead`	One lead with custom fields and sequence progress	Read
`find_lead_by_email`	Finds leads by email across all campaigns	Read
`update_lead`	Changes a lead's fields, tags, custom fields or status	Write
`bulk_set_lead_status`	Sets the same status on up to 1000 leads	Write
`bulk_add_lead_tags`	Adds tags to up to 1000 leads	Write
`bulk_remove_lead_tags`	Removes tags from up to 1000 leads	Write
`delete_leads`	Deletes leads from a campaign by ids, by filter, or all	Write

Emails

Tool	What it does	Access
`list_emails`	Emails across all mailboxes (unified inbox), newest first, without bodies	Read
`get_email`	One email with its body as plain text; `includeHtml: true` adds the HTML version (returned anyway when the email has no text part; `htmlOmitted` marks that it was left out). Bodies over 25,000 characters are cut and marked `bodyTruncated`	Read
`count_unread_emails`	Number of unread emails	Read
`reply_to_email`	Sends a reply in the conversation, from the mailbox that owns it	Sends email
`forward_email`	Forwards an email to recipients you choose	Sends email
`mark_thread_read`	Marks a conversation as read	Write

Analytics and Lead Finder

Tool	What it does	Access
`get_campaign_analytics`	A campaign's sends, opens, clicks, replies, bounces and rates, by mailbox, step or bounce type, optionally over time	Read
`get_workspace_analytics`	Totals and rates across all campaigns for a period	Read
`list_lead_searches` / `get_lead_search`	Lead Finder searches and their progress (searches are started in the dashboard)	Read

Safety

Campaigns start as drafts. Starting is always a separate step, so you can review the sequence and get a test email first.
No passwords in chat. Google Workspace and Microsoft 365 mailboxes connect through start_oauth_connect - a link you open yourself. SMTP/IMAP mailboxes are connected in the dashboard (or with an API key connection); passwords are stored encrypted and never returned.
Your AI app receives what the tools return. Email content, lead data and analytics the assistant reads go to the AI provider you use (Anthropic, OpenAI, …) and are handled under its terms. MailBeast sees only the tool calls, not your conversation. See our Privacy Policy.
Treat incoming emails as untrusted. A reply from a lead can contain text written to steer an AI assistant. Check what the assistant proposes before you approve a send, a deletion or a bulk change.

Troubleshooting

Symptom	What to do
"MCP is available on the Pro+ plan" next to a workspace	MCP needs Pro+ (or enterprise with API access). Pick another workspace or change the plan in the dashboard
"Only workspace owners and admins can connect apps"	Ask an owner or admin of that workspace to connect, or to change your role
"This connection request has expired"	A sign-in request lasts 30 minutes and works once - start connecting again from the app
The assistant has no tools to create, change or send	You connected with Make changes and send email off. Connect again with it on and delete the old key
`connect_mailboxes` is missing	Sign-in connections don't take passwords. Use `start_oauth_connect` for Google / Microsoft, or connect SMTP/IMAP in the dashboard
The app shows Reconnect / "Authorization failed" / `401`	The key was deleted or the connection expired. Connect again
Claude: "Couldn't reach the MCP server"	Check that your network allows `mcp.mailbeast.ai`, then reconnect. If it persists, send us the `ofid_…` reference Claude shows
Claude Code: the browser didn't open	Copy the URL Claude Code prints, open it, approve, then run `/mcp` again
`429` / "Too many requests"	The workspace rate limit (shared with the REST API) - wait for the time in the message
`402` / "plan limit reached"	A plan limit is used up - ask "what's left on my plan?" (`get_workspace`)

Still stuck? Write to support@mailbeast.ai or use the chat in the app.

Example prompts

"How many emails can I still send this month?"
"Show me reply rates for my campaigns this week."
"Create a 3-step campaign for these leads, weekdays 9-17 their time, and send me a test of step 1."
"Which mailboxes are failing and why?"
"Summarize today's unread replies and draft answers to the interested ones."
"Compare reply rates of my last three campaigns by sequence step."

Note

https://developer.mailbeast.ai/mcp is a different server: it searches this documentation and does not touch your workspace. It's useful for agents that write code against the API.

This documentation is built and hosted on Mintlify, a developer documentation platform.