One API, four ways to read it
Mailgi is a REST API at api.mailgi.xyz. Here is which documentation to open, depending on whether you are a person, a tool or an agent.
Mailgi's API is documented four times, for four different readers. SKILL.md is for an agent, Swagger UI for a developer, openapi.json for tooling, and llms.txt for an AI crawler. They describe the same REST API at https://api.mailgi.xyz, and the MCP server and SDK wrap it one-to-one.
Pick the surface for your reader
Same API, different shapes. If you are not sure, an agent wants SKILL.md and a person wants the guides.
| Surface | Who it's for | What it is | Use it when |
|---|---|---|---|
| SKILL.md | An agent | The whole API in plain language, versioned, small enough for one context window. | You want an agent to onboard itself and act on the API directly. |
| Swagger UI | A developer | Interactive explorer for every endpoint, with request and response schemas. | You want to try a call in the browser or check a field. |
| openapi.json | Tooling | The machine-readable OpenAPI spec. | You are generating a client or validating requests. |
| MCP server | An MCP client | https://api.mailgi.xyz/mcp: every REST endpoint as a tool. | You use Claude Code, Claude Desktop or Cursor. |
| @mailgi/mailgi | A Node developer | TypeScript SDK and the mailgi CLI, methods 1:1 with REST. | You'd rather call typed methods than fetch. |
| llms.txt | An LLM crawler | A one-page site summary with links to everything above. | An assistant needs to find the right page quickly. |
The whole loop in three calls
Every Mailgi integration starts here. Mail between Mailgi addresses is free, so this costs nothing to run.
Register, send, read
Base URL https://api.mailgi.xyz. Authenticated calls take Authorization: Bearer amb_….
Wait a couple of seconds after registering before the first send: the mailbox is provisioned asynchronously. Retry once on a 5xx.
# 1. Register: no auth, no signup form
curl -s -X POST https://api.mailgi.xyz/v1/agents/register \
-H "Content-Type: application/json" -d '{"label":"my-agent"}'
# => {"emailAddress":"buzzing-falcon@mailgi.xyz","apiKey":"amb_..."}
# 2. Send (free between Mailgi addresses)
curl -s -X POST https://api.mailgi.xyz/v1/mail/send \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"to":["buzzing-falcon@mailgi.xyz"],"subject":"Hi","textBody":"Hello"}'
# 3. Read the inbox
curl -s https://api.mailgi.xyz/v1/mail -H "Authorization: Bearer $KEY"
Endpoints at a glance
The full reference, with every field and error code, is in SKILL.md and Swagger. Errors are always {"error":{"code","message"}}; match on the code, not the status.
| Endpoint | Auth | What it does |
|---|---|---|
| POST /v1/agents/register | none | Create an agent and its mailbox; returns the address and an API key (shown once). |
| GET /v1/mail | API key | List messages: folder, limit, position, sort. No search. |
| GET /v1/mail/<id> | API key | One message with its text and HTML body. |
| POST /v1/mail/send | API key | Send: to, cc, bcc, subject, textBody, htmlBody, replyTo. Other fields are ignored. |
| /v1/mailboxes | API key | List, create, rename and delete folders. |
| /v1/webhook-endpoints | API key | Signed notifications when mail arrives; deliveries log, resend, re-enable. |
| /v1/apikeys | API key | Create, list and revoke extra keys. |
| GET /v1/billing | API key | Balance, wallet standing, live prices, top-up links. |
| GET /health/ready | none | Readiness: database and mail server. |
Guides that go further
How to give an AI agent an email address
The options, how each fails, and the setup in depth, including DKIM, SPF and DMARC.
Receiving a verification code
Register, poll, extract the code, and avoid the four common failure modes.
Running a support inbox
Custom-domain setup, folders as ticket status, and replies without threading headers.
One POST to start.
No signup form, no OAuth, no card to start. Receiving is free.
Open the dashboard →