Connect any agent to Mailrun.

Choose your integration

Mailrun Agent Identities gives your agent a durable email address on a company-controlled domain and, optionally, a phone number. You bring the model, prompts, and tools; Mailrun provides the channels and records.

API reference and guides

The API base is https://agent-api.mailrun.ai, with endpoints under /v1. Use the reference for endpoint schemas and the workflow guide for lifecycle and event handling.

• API reference. Swagger UI documents every endpoint and its schemas. Open the API reference
• Workflow guide. A plain Markdown document covering what the API is, domain onboarding, identity lifecycle, sending and reading mail, webhooks and events in section 5, the status-machine reference, and the error catalog. It also covers usage, metered voice billing, and voicemail. Read the workflow guide
• OpenAPI document. The OpenAPI 3 specification in YAML, ready to import into tools and code generators. Get the OpenAPI document
• API quickstart. A curl walkthrough on this site: create an identity, send an email, and read the reply. Follow the API quickstart
• OAuth authorization-server metadata. An MCP client that supports sign-in reads this RFC 8414 metadata to discover the sign-in endpoints. Today, sign-in is allowed only for Claude’s official apps and Claude Code; other clients use an API key. Read the sign-in metadata

Connect an MCP client

Use https://agent-api.mailrun.ai/mcp with Streamable HTTP transport. API keys work with any remote MCP client that lets you set a bearer token.

1. Create an API key at https://app.mailrun.ai/agent with only the scopes your agent needs. In an official Claude app or Claude Code, you can choose sign-in instead.
2. Open your client’s MCP settings, which may be called Connectors, Integrations, or MCP servers. Add a remote server with the URL https://agent-api.mailrun.ai/mcp and select Streamable HTTP transport.
3. Set the Authorization header to Bearer <your API key>. If your client supports sign-in and Mailrun allows it, complete the sign-in prompt instead.
4. Enable the tools you want and try a read-only call first: “List my Mailrun agent identities.”

This is the Claude Code command to add the server. Other clients take the same URL in their own MCP settings.

claude mcp add --transport http mailrun https://agent-api.mailrun.ai/mcp

Notes for your client

• Claude. Sign in with your Mailrun account from claude.ai or the official desktop and mobile apps. Follow the Claude guide
• Claude Code. Add the server with the terminal command above, then start Claude Code and run /mcp to choose Mailrun and sign in. See the Claude Code steps
• Other MCP clients. For ChatGPT, Cursor, VS Code, or a custom agent, use the same server URL with an API key as the bearer token, provided your client lets you set one. Check that capability in your client’s MCP settings.
• Sign-in for another client. Contact Mailrun to ask about enabling sign-in for your client. Other clients use an API key today. Contact Mailrun

Webhooks and replies

Yes, Mailrun supports webhooks. You don’t need to poll for replies. Register an HTTPS receiver with POST /v1/webhooks or the create_webhook MCP tool, then choose the event types to receive. An empty event-type list subscribes to all types.

When new mail arrives, Mailrun’s mail server pushes it to the API. The API records an email.received event and POSTs it to every subscribed endpoint. Other events cover sending, delivery failures, calls, voicemail, domain lifecycle, and usage; the full list is in section 5 of the workflow guide.

• Read the message. An email.received event carries message_id, thread_id, and size_bytes, never the subject or body. Fetch the message with GET /v1/identities/{id}/messages/{messageId}, using message_id as messageId. A reply to an email your agent sent has the same thread_id.
• Verify each delivery. X-Mailrun-Timestamp contains Unix seconds. X-Mailrun-Signature contains sha256=<hex>, the HMAC-SHA256 of {timestamp}.{raw body} using your endpoint’s secret. Verify the signature against the raw body and reject timestamps more than 300 seconds from your clock. Save the whsec_... secret when you create the endpoint: it is returned once and cannot be read back. To rotate it, delete and recreate the endpoint.
• Handle retries and gaps. Return a 2xx quickly. Non-2xx responses trigger retries with exponential backoff, up to six attempts. An endpoint that keeps failing is automatically disabled and a webhook.endpoint_disabled event is recorded; PATCH the endpoint to re-enable it. Deliveries can repeat, so deduplicate on the event id. If your receiver was down, recover missed events with GET /v1/events?since=<ISO timestamp>. It returns the same envelope as the webhook. Events are retained for 90 days.

Read section 5: Webhooks and events (plain Markdown)

Keys, scopes, and sign-in

You need an Agent Identities account; access is by request. Both the HTTP API and MCP server use an Authorization: Bearer header. Create API keys at https://app.mailrun.ai/agent and give each integration only the scopes it needs. Keep keys on a server or trusted machine, never in browser code. Keys and sign-in use the same scopes. Rate limits, daily send caps per identity, and package allowances apply identically through MCP and HTTP.

OAuth sign-in lets you use your Mailrun account and review permissions without copying a key. Today, only claude.ai, Claude’s official desktop and mobile apps, and Claude Code can start sign-in because Mailrun restricts which apps are allowed. Other clients use an API key; contact Mailrun to ask about enabling sign-in for another client.

Manage API keys and connected apps

Read what each permission allows

Get help with an integration

When you contact Mailrun, include the identity id, the request_id from the error response, and the time the issue occurred.

Contact Mailrun