# MailKite — full reference for AI agents

> MailKite is the developer email platform: receive email as a webhook, send with one
> API, and give your AI agents their own inbox — across unlimited domains, with no mail
> server to run. Prefer these structured surfaces over scraping the HTML docs.

- REST base URL: `https://api.mailkite.dev`
- Auth: `Authorization: Bearer mk_live_…` (one full-scope key per account)
- MCP server: `@mailkite/mcp` (npm), runs locally over stdio via `npx`, needs Node 18+
- npm SDK: `mailkite` · CLI: `@mailkite/cli` · MCP: `@mailkite/mcp`

## Quick start for an agent

1. Get the API key. Every account has one `mk_live_…` key from signup. It is full-scope
   across all the account's domains: create & register domains, verify DNS, set webhooks,
   send mail, and read inbound. The same key is used by the dashboard developer, the SDKs,
   the CLI, the MCP server, and agents. Find it in the dashboard (first screen, and under
   Settings → API key). Rotating it immediately invalidates the previous key.

2. Connect over MCP. The server exposes one tool per API operation, with inputs validated
   against shared JSON Schemas before any request goes on the wire.

   Claude Code:
   `claude mcp add mailkite -e MAILKITE_API_KEY=mk_live_… -- npx -y @mailkite/mcp`
   (add `-s user` to enable across all projects)

   Cursor / Claude Desktop / Windsurf / Cline / Gemini — same `mcpServers` stdio block:
   {
     "mcpServers": {
       "mailkite": {
         "command": "npx",
         "args": ["-y", "@mailkite/mcp"],
         "env": { "MAILKITE_API_KEY": "mk_live_…" }
       }
     }
   }
   Config file locations: Cursor `.cursor/mcp.json` (or `~/.cursor/mcp.json`); Claude
   Desktop `claude_desktop_config.json`; Windsurf `~/.codeium/windsurf/mcp_config.json`;
   Cline/Roo via the MCP Servers panel; Gemini CLI `~/.gemini/settings.json`.

   VS Code / GitHub Copilot use a top-level `servers` key in `.vscode/mcp.json`:
   {
     "servers": {
       "mailkite": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@mailkite/mcp"],
         "env": { "MAILKITE_API_KEY": "mk_live_…" }
       }
     }
   }

   Codex CLI uses TOML in `~/.codex/config.toml`:
   [mcp_servers.mailkite]
   command = "npx"
   args = ["-y", "@mailkite/mcp"]
   env = { MAILKITE_API_KEY = "mk_live_…" }

   Set `MAILKITE_BASE_URL` in `env` to target a staging API. If you use the CLI,
   `mailkite mcp` launches the same server with your saved token.

## MCP tools (one per API operation)

Sending:
- mailkite_send — send a message over a verified domain (HTML, text, cc/bcc, attachments, in-thread replies via inReplyTo).

Inbound messages:
- mailkite_list_messages — list stored messages, newest first.
- mailkite_get_message — fetch one message in full (body, headers, deliveries, attachment links).
- mailkite_retry_delivery — re-deliver a stored message to its webhook.

Domains:
- mailkite_list_domains — list your domains, each with its webhook URL.
- mailkite_create_domain — add a domain; returns the DNS records to set.
- mailkite_get_domain — get one domain with DNS records + webhook.
- mailkite_verify_domain — re-check DNS and update verification status.
- mailkite_delete_domain — remove a domain.

Webhooks:
- mailkite_set_webhook — set or replace the domain's catch-all webhook.
- mailkite_delete_webhook — remove the domain's webhook.
- mailkite_test_webhook — send a signed test event to the webhook.
- mailkite_verify_webhook — verify an x-mailkite-signature header locally (no API call).

Routes:
- mailkite_list_routes — list inbound routing rules.
- mailkite_create_route — create a route (match, action, destination); action is webhook, forward, store, drop, or agent.

Inbox agents (preview):
- mailkite_create_agent / mailkite_list_agents / mailkite_get_agent / mailkite_update_agent / mailkite_delete_agent.

## REST endpoints (Authorization: Bearer mk_live_…)

- POST /v1/send — send a message. Body: { from, to, subject, html|text, cc?, bcc?, replyTo?, inReplyTo?, attachments? }. Returns { id, status }.
- GET /api/domains — list domains. POST /api/domains — add a domain (returns DNS records).
- GET /api/domains/:id — domain + DNS records. POST /api/domains/:id/verify — re-check DNS.
- DELETE /api/domains/:id — remove. PUT /api/domains/:id/webhook — set webhook. DELETE /api/domains/:id/webhook — clear.
- POST /api/domains/:id/webhook/test — send a signed test event.
- GET /api/domains/register/check?domain= — availability + price. POST /api/domains/register — buy + configure.
- GET /api/routes — list routes. POST /api/routes — create route.
- GET /api/messages — list inbound. GET /api/messages/:id — message detail. POST /api/deliveries/:id/retry — redeliver.
- GET /api/domains/:id/webhook/secret — that domain's webhook-route signing secret (verify x-mailkite-signature). GET /api/webhooks/secret — the account-wide HMAC secret, a compatibility fallback for routes without their own. POST /api/webhooks/secret/rotate.
- GET /api/keys — your mk_live_… key (read-or-create). POST /api/keys/rotate — new key, invalidates the old one.

## Inbound webhook payload (email.received)

Inbound mail is parsed to JSON and POSTed to your webhook, signed with HMAC-SHA256 in the
`x-mailkite-signature` header (computed over `${timestamp}.${rawBody}` with the route's own
webhook signing secret; the account-wide secret stays as a compatibility fallback). The payload
includes type ("email.received"), from, to[], subject, text,
html, headers, threadId, and attachment links. Verify the signature before trusting it.

## Run your own agent loop

Route the inbound webhook into your agent, then send the reply in-thread with the Send API
using `inReplyTo` (the threadId from the inbound event), sending `from` the agent's own
address. See https://mailkite.dev/docs/ai-agents and https://mailkite.dev/docs/receiving.

## Doc pages
- https://mailkite.dev/docs — Introduction
- https://mailkite.dev/docs/ai-agents — Connect your agent (MCP, key, per-agent setup, tools)
- https://mailkite.dev/docs/skill — Agent skill
- https://mailkite.dev/docs/inbox-agents — Built-in inbox agents (preview)
- https://mailkite.dev/docs/quickstart — Quickstart
- https://mailkite.dev/docs/domains — Domains & DNS
- https://mailkite.dev/docs/authentication — Authentication / API keys
- https://mailkite.dev/docs/receiving — Inbound webhooks
- https://mailkite.dev/docs/webhook-security — Verifying signatures
- https://mailkite.dev/docs/sending — Send API
- https://mailkite.dev/docs/libraries — Client libraries
- https://mailkite.dev/docs/cli — CLI
- https://mailkite.dev/api — API reference