# mails.ai documentation

> mails.ai is the email API for AI agents.

Every link below is a page's Markdown copy: any docs page is also plain Markdown at its URL plus `.md`. The HTML pages are at the same URLs without `.md`.

## Get started

- [Introduction](https://mails.ai/docs/index.md): mails.ai is the email API for AI agents.
- [Quickstart](https://mails.ai/docs/quickstart.md): Key → first send (your agent is created automatically) → first reply event. The five-minute path through the REST API, with copy-paste curl and fetch.
- [Authentication](https://mails.ai/docs/authentication.md): Bearer keys, the mk_live_ format, four scopes (send / read / manage / draft), live vs test mode, and rotation. Everything about authenticating a request.
- [Core concepts](https://mails.ai/docs/concepts.md): Workspace, agent, message, event, thread, draft, webhook, suppression, reputation — the eight nouns the API is built from, and how they fit together.
- [Python](https://mails.ai/docs/send-with-python.md): Install mailsai, set MAILS_API_KEY, send one message, and read the reply your agent gets back.
- [cURL](https://mails.ai/docs/send-with-curl.md): No SDK, no install: one POST sends the message and one GET shows the reply.
- [Next.js](https://mails.ai/docs/send-with-nextjs.md): One route handler sends, one receives signed reply events. App Router, server-side only.
- [Express](https://mails.ai/docs/send-with-express.md): One Express server: a route that sends, and a webhook route that receives signed reply events.
- [FastAPI](https://mails.ai/docs/send-with-fastapi.md): One FastAPI app: a route that sends, and a webhook route that receives signed reply events.

## Learn

- [Inbound](https://mails.ai/docs/inbound.md): Every agent has an address that receives mail. Replies to its own sends are told apart from new mail.
- [Attachments](https://mails.ai/docs/attachments.md): Attach up to 10 files to an email you send, and download the files on mail your agents receive.
- [Search](https://mails.ai/docs/search.md): Find received and sent mail by words, sender, recipient, date, folder or label.
- [Folders and labels](https://mails.ai/docs/folders-and-labels.md): Every thread sits in one folder and can carry labels. Both work as filters on lists and search.
- [Events & streaming](https://mails.ai/docs/events.md): List events or tail the live SSE stream. Every event type, the inbound payload, and a reconnect-safe consumer.
- [Webhooks](https://mails.ai/docs/webhooks.md): Register an endpoint, verify the HMAC signature, handle retries. The push half of the events model, done safely.

## Resources

- [SDKs](https://mails.ai/docs/sdks.md): The TypeScript SDK and the MCP server are on npm, the Python SDK is on PyPI. All thin wrappers over the same REST surface.
- [CLI](https://mails.ai/docs/cli.md): Send and receive email, follow events and set up AI clients from your terminal. Tables for people, JSON for scripts and agents.
- [MCP server](https://mails.ai/docs/mcp.md): Give an AI client email tools: the hosted server, or the local one through npx.
- [Agent skills](https://mails.ai/docs/agent-skills.md): Instructions an AI agent loads when it works with mails.ai: sending and receiving, acting on inbound mail safely, and staying within the rules.
- [Integrations](https://mails.ai/docs/integrations.md): Connect mails.ai to the frameworks and clients you already use.

## Knowledge base

- [Introduction](https://mails.ai/docs/knowledge-base.md): Answers to what comes up once agents send and receive real mail.

## Agent frameworks

- [Claude Agent SDK](https://mails.ai/docs/claude-agent-sdk.md): Connect a Claude agent to the hosted MCP server, in TypeScript or Python.
- [OpenAI Agents SDK](https://mails.ai/docs/openai-agents-sdk.md): Connect an OpenAI agent to the hosted MCP server, in Python or TypeScript.
- [Vercel AI SDK](https://mails.ai/docs/vercel-ai-sdk.md): Turn the mails.ai MCP tools into AI SDK tools, in TypeScript.
- [LangGraph](https://mails.ai/docs/langgraph.md): Load the mails.ai MCP tools into a LangGraph agent, in Python.
- [CrewAI](https://mails.ai/docs/crewai.md): Give a crew's agent the mails.ai MCP tools, in Python.

## API Reference

- [Introduction](https://mails.ai/docs/api-reference.md): Every endpoint, with the exact request and response fields — messages, batch, received, events, webhooks, agents, keys, suppression.
- [Errors](https://mails.ai/docs/errors.md): One envelope on every failure — type, code, message, param, request_id. The type → status mapping and the full code list.
- [Limits](https://mails.ai/docs/limits.md): Per-tier send caps, single-message payload limits, and the 429s you get past them, which say when to retry.

## API Reference: Sending

- [Send a message](https://mails.ai/docs/api-reference/messages/send-message.md): POST /v1/messages
- [List sent messages](https://mails.ai/docs/api-reference/messages/list-messages.md): GET /v1/messages
- [Send a batch](https://mails.ai/docs/api-reference/messages/batch-send-messages.md): POST /v1/messages/batch
- [Appeal a refusal](https://mails.ai/docs/api-reference/messages/appeal-message.md): POST /v1/messages/appeal
- [Retrieve a sent message](https://mails.ai/docs/api-reference/messages/get-message.md): GET /v1/messages/{id}
- [Reschedule a message](https://mails.ai/docs/api-reference/messages/reschedule-message.md): PATCH /v1/messages/{id}
- [Reply to a message](https://mails.ai/docs/api-reference/messages/reply-message.md): POST /v1/messages/{id}/reply
- [Forward a message](https://mails.ai/docs/api-reference/messages/forward-message.md): POST /v1/messages/{id}/forward
- [Cancel a scheduled send](https://mails.ai/docs/api-reference/messages/cancel-message.md): POST /v1/messages/{id}/cancel
- [Download raw .eml](https://mails.ai/docs/api-reference/messages/get-message-raw.md): GET /v1/messages/{id}/raw

## API Reference: Receiving

- [List received messages](https://mails.ai/docs/api-reference/inbound/list-received-messages.md): GET /v1/messages/received
- [Retrieve received mail](https://mails.ai/docs/api-reference/inbound/get-received-message.md): GET /v1/messages/received/{id}
- [List attachments](https://mails.ai/docs/api-reference/inbound/list-received-attachments.md): GET /v1/messages/received/{id}/attachments
- [Download an attachment](https://mails.ai/docs/api-reference/inbound/download-received-attachment.md): GET /v1/messages/received/{id}/attachments/{attachment_id}
- [Simulate inbound mail](https://mails.ai/docs/api-reference/inbound/simulate-inbound.md): POST /v1/test/inbound

## API Reference: Threads

- [List threads](https://mails.ai/docs/api-reference/threads/list-threads.md): GET /v1/threads
- [Retrieve a thread](https://mails.ai/docs/api-reference/threads/get-thread.md): GET /v1/threads/{id}
- [Update a thread](https://mails.ai/docs/api-reference/threads/update-thread.md): PATCH /v1/threads/{id}
- [Trash or delete a thread](https://mails.ai/docs/api-reference/threads/delete-thread.md): DELETE /v1/threads/{id}

## API Reference: Drafts

- [Create a draft](https://mails.ai/docs/api-reference/drafts/create-draft.md): POST /v1/drafts
- [List drafts](https://mails.ai/docs/api-reference/drafts/list-drafts.md): GET /v1/drafts
- [Retrieve a draft](https://mails.ai/docs/api-reference/drafts/get-draft.md): GET /v1/drafts/{id}
- [Update a draft](https://mails.ai/docs/api-reference/drafts/update-draft.md): PATCH /v1/drafts/{id}
- [Delete a draft](https://mails.ai/docs/api-reference/drafts/delete-draft.md): DELETE /v1/drafts/{id}
- [Send a draft](https://mails.ai/docs/api-reference/drafts/send-draft.md): POST /v1/drafts/{id}/send

## API Reference: Labels

- [Create a label](https://mails.ai/docs/api-reference/labels/create-label.md): POST /v1/labels
- [List labels](https://mails.ai/docs/api-reference/labels/list-labels.md): GET /v1/labels
- [Retrieve a label](https://mails.ai/docs/api-reference/labels/get-label.md): GET /v1/labels/{id}
- [Update a label](https://mails.ai/docs/api-reference/labels/update-label.md): PATCH /v1/labels/{id}
- [Delete a label](https://mails.ai/docs/api-reference/labels/delete-label.md): DELETE /v1/labels/{id}

## API Reference: Search

- [Search mail](https://mails.ai/docs/api-reference/search/search-mail.md): GET /v1/search

## API Reference: Agents

- [Create an agent](https://mails.ai/docs/api-reference/agents/create-agent.md): POST /v1/agents
- [List agents](https://mails.ai/docs/api-reference/agents/list-agents.md): GET /v1/agents
- [Retrieve an agent](https://mails.ai/docs/api-reference/agents/get-agent.md): GET /v1/agents/{id}
- [Update an agent](https://mails.ai/docs/api-reference/agents/update-agent.md): PATCH /v1/agents/{id}
- [Archive an agent](https://mails.ai/docs/api-reference/agents/archive-agent.md): DELETE /v1/agents/{id}
- [Test forwarding](https://mails.ai/docs/api-reference/agents/verify-agent-forwarding.md): POST /v1/agents/{id}/forwarding/verify
- [Inbox summary](https://mails.ai/docs/api-reference/agents/get-agent-inbox.md): GET /v1/agents/{id}/inbox

## API Reference: Events

- [List events](https://mails.ai/docs/api-reference/events/list-events.md): GET /v1/events
- [Retrieve an event](https://mails.ai/docs/api-reference/events/get-event.md): GET /v1/events/{id}
- [Redeliver an event](https://mails.ai/docs/api-reference/events/redeliver-event.md): POST /v1/events/{id}/redeliver
- [Stream events (SSE)](https://mails.ai/docs/api-reference/events/stream-events.md): GET /v1/events/stream

## API Reference: Webhooks

- [Create a webhook](https://mails.ai/docs/api-reference/webhooks/create-webhook.md): POST /v1/webhooks
- [List webhook endpoints](https://mails.ai/docs/api-reference/webhooks/list-webhooks.md): GET /v1/webhooks
- [Retrieve a webhook](https://mails.ai/docs/api-reference/webhooks/get-webhook.md): GET /v1/webhooks/{id}
- [Update a webhook](https://mails.ai/docs/api-reference/webhooks/update-webhook.md): PATCH /v1/webhooks/{id}
- [Delete a webhook](https://mails.ai/docs/api-reference/webhooks/delete-webhook.md): DELETE /v1/webhooks/{id}
- [Rotate the signing secret](https://mails.ai/docs/api-reference/webhooks/rotate-webhook-secret.md): POST /v1/webhooks/{id}/rotate-secret
- [List delivery attempts](https://mails.ai/docs/api-reference/webhooks/list-webhook-deliveries.md): GET /v1/webhooks/{id}/deliveries
- [Send a test event](https://mails.ai/docs/api-reference/webhooks/test-webhook.md): POST /v1/webhooks/{id}/test
- [Replay a delivery](https://mails.ai/docs/api-reference/webhooks/replay-webhook-delivery.md): POST /v1/webhook-deliveries/{id}/replay

## API Reference: Suppression

- [Look up suppression](https://mails.ai/docs/api-reference/suppression/list-suppression.md): GET /v1/suppression
- [Add an allowlist entry](https://mails.ai/docs/api-reference/suppression/allow-suppression.md): POST /v1/suppression/allow
- [Revoke an allowlist entry](https://mails.ai/docs/api-reference/suppression/revoke-suppression-allow.md): DELETE /v1/suppression/allow/{id}

## API Reference: Domains

- [Add a send domain](https://mails.ai/docs/api-reference/domains/create-domain.md): POST /v1/domains
- [List custom domains](https://mails.ai/docs/api-reference/domains/list-domains.md): GET /v1/domains
- [Get a domain](https://mails.ai/docs/api-reference/domains/get-domain.md): GET /v1/domains/{id}
- [Remove a domain](https://mails.ai/docs/api-reference/domains/delete-domain.md): DELETE /v1/domains/{id}
- [Verify a domain now](https://mails.ai/docs/api-reference/domains/verify-domain.md): POST /v1/domains/{id}/verify

## API Reference: Reputation

- [Get reputation](https://mails.ai/docs/api-reference/reputation/get-reputation.md): GET /v1/reputation

## API Reference: Metrics

- [Mail metrics](https://mails.ai/docs/api-reference/metrics/get-metrics.md): GET /v1/metrics

## API Reference: Logs

- [List audit logs](https://mails.ai/docs/api-reference/logs/list-logs.md): GET /v1/logs

## API Reference: API Keys

- [Create an API key](https://mails.ai/docs/api-reference/api-keys/create-api-key.md): POST /v1/api-keys
- [List API keys](https://mails.ai/docs/api-reference/api-keys/list-api-keys.md): GET /v1/api-keys
- [Revoke an API key](https://mails.ai/docs/api-reference/api-keys/revoke-api-key.md): DELETE /v1/api-keys/{id}

## API Reference: Connected Apps

- [List connected apps](https://mails.ai/docs/api-reference/connected-apps/list-connected-apps.md): GET /v1/oauth/grants
- [Revoke a connected app](https://mails.ai/docs/api-reference/connected-apps/revoke-connected-app.md): DELETE /v1/oauth/grants/{id}

## API Reference: Billing

- [Get current usage](https://mails.ai/docs/api-reference/billing/get-billing-usage.md): GET /v1/billing/usage
- [Open billing portal](https://mails.ai/docs/api-reference/billing/open-billing-portal.md): POST /v1/billing/portal

## API Reference: Account

- [Identify the current key](https://mails.ai/docs/api-reference/account/get-me.md): GET /v1/me

## API Reference: Public

- [One-click unsubscribe](https://mails.ai/docs/api-reference/public/unsubscribe-one-click.md): POST /v1/unsubscribe
- [Unsubscribe page](https://mails.ai/docs/api-reference/public/unsubscribe.md): GET /v1/unsubscribe
- [Health check](https://mails.ai/docs/api-reference/public/get-health.md): GET /api/health