MCP
The Mailbay MCP server gives any agent the same actions as the API, with tool descriptions written for agents.
Remote server
Point your MCP client at https://mcp.mailbay.dev/mcp (streamable HTTP) and send your API key as Authorization: Bearer mb_live_…. Create a key on the API keys page of the dashboard. OAuth sign in, so a client needs no key, is coming.
claude mcp add --transport http mailbay https://mcp.mailbay.dev/mcp \
--header "Authorization: Bearer $MAILBAY_API_KEY"Local server
mailbay-mcp stdio runs the server over stdio with an API key and forwards to the remote server. Add it to any client that reads an mcpServers config.
{
"mcpServers": {
"mailbay": {
"command": "mailbay-mcp",
"args": ["stdio"],
"env": { "MAILBAY_API_KEY": "mb_live_..." }
}
}
}Tools
| Field | Type | Description |
|---|---|---|
| create_inbox | inbox | Create an address on your subdomain or a verified domain. |
| list_inboxes | inbox[] | Every inbox the key can see. |
| get_inbox | inbox | One inbox by id. |
| delete_inbox | Delete an inbox and its mail. | |
| list_messages | message[] | Messages in an inbox, newest first. |
| send_email | message | Send from an inbox. Respects suppressions and limits. |
| reply | message | Reply in a thread with the right threading headers. |
| list_threads | thread[] | Threads in an inbox, most recent first. |
| get_thread | thread | A thread with all its messages. |
| get_message | message | One message with auth results and attachments. |
| wait_for_email | message, codes, links | Block until a matching message arrives. Filters: from, subject_contains, to (one recipient address). |
| add_domain | domain | Start adding a custom domain. |
| verify_domain | domain | Check the DNS records now. |
| create_webhook | webhook | Get events such as message.received at your URL. |
| list_domains | domain[] | Your domains and their status. |
Example: sign up flow
Ask your agent to sign up for a service. It needs two Mailbay tool calls: one to get an address, one to get the code.
create_inbox({ "local_part": "signup-bot" })
// { "id": "ibx_01jbz8w4k2q9", "address": "signup-bot@k7m3qz.mailbay.email", ... }
// ...the agent fills in the sign up form with that address...
wait_for_email({ "inbox_id": "ibx_01jbz8w4k2q9", "subject_contains": "code", "timeout_seconds": 60 })
// { "message": { "subject": "Your sign in code", ... }, "codes": ["482913"], "links": [] }Or skip creating an inbox: any address under your code reaches the Catch-all, so the agent can make up a fresh address per sign up and wait on the Catch-all with to.
wait_for_email({ "inbox_id": "ibx_catchall", "to": "signup-42@k7m3qz.mailbay.email", "timeout_seconds": 60 })