# Mailgi

> Email infrastructure for AI agents. Real inboxes, real deliverability, one REST API — an agent registers its own address in one POST, sends/receives/reads mail as JSON, and can send as a customer's own verified domain with DKIM/SPF/DMARC handled automatically.

Mailgi is not a bulk/marketing email platform. Every send is a single, explicit, transactional API call specifying its own recipient — there are no mailing lists, imports, or campaigns anywhere in the product.

## Start here

- [SKILL.md](https://www.mailgi.xyz/SKILL.md): the complete API reference, written in plain language for an AI agent to read and act on directly. Start here if you are an agent.
- [Docs](https://www.mailgi.xyz/docs.html): which documentation to read for whom (SKILL.md for agents, Swagger for developers, OpenAPI for tooling, MCP, SDK), the three-call quick start and an endpoint table.
- [llms-full.txt](https://www.mailgi.xyz/llms-full.txt): every guide, comparison and reference page on this site as one plain-text file, generated from the HTML.
- [API docs (Swagger UI)](https://api.mailgi.xyz/docs): interactive, human-browsable API explorer.
- [OpenAPI spec](https://api.mailgi.xyz/openapi.json): machine-readable spec for tooling/codegen.
- [Dashboard](https://app.mailgi.xyz): where a human attaches a custom domain, invites their team, and issues registration tokens for agents.
- [For agents](https://www.mailgi.xyz/agents.html): the agent-first onboarding page (SKILL.md usage, raw API examples, CLI, SDK, MCP).
- [MCP server](https://www.mailgi.xyz/mcp.html): hosted Model Context Protocol server at https://api.mailgi.xyz/mcp (Streamable HTTP, stateless). Credentials are headers: `Authorization: Bearer amb_…` for agent tools, `X-Mailgi-Session` for org tools; with neither, only public tools (register_agent, org_login_request_code, org_login_verify, topup_*, health). Every tool is a 1:1 proxy of a REST endpoint — same behaviour, limits and billing. No OAuth yet, so it cannot be added as a claude.ai or ChatGPT hosted connector.

## Guides

- [How to give an AI agent an email address](https://www.mailgi.xyz/agent-email-address.html): why an agent needs its own mailbox, the four common approaches and how each fails, a working setup in one POST, and what DKIM/SPF/DMARC actually do.
- [Choosing an email API for an AI agent](https://www.mailgi.xyz/choosing-an-email-api-for-ai-agents.html): why deliverability is the wrong axis to compare on, and the four questions that decide it — mailbox or webhook, who creates the account, how long mail is kept, whose domain.
- [Mailgi vs Resend, Postmark, Mailgun and AgentMail](https://www.mailgi.xyz/vs-resend-postmark-mailgun.html): a dated, sourced comparison of the alternatives, including an explicit section on when to pick something other than Mailgi. Facts last verified 2026-10-31.
- [Best email API for AI agents in 2026](https://www.mailgi.xyz/best-email-api-for-ai-agents.html): an honest, dated ranking of eight email APIs for AI agents (AgentMail, Mailgi, Resend, Nylas, mails.ai, Cloudflare, Postmark, Mailgun/SendGrid) and how to pick.
- [AgentMail alternative: Mailgi compared](https://www.mailgi.xyz/agentmail-alternative.html): Mailgi vs AgentMail line by line — self-registration, per-inbox pricing, threads, search, SOC 2 — and when to stay on AgentMail.
- [Resend for AI agents](https://www.mailgi.xyz/resend-for-ai-agents.html): what Resend Inboxes (launched 2026-10-22) change for agents, versus Mailgi on self-signup, receiving costs and retention.
- [Should your AI agent use the Gmail API?](https://www.mailgi.xyz/gmail-api-for-ai-agents.html): OAuth verification, the 100-user cap, CASA assessments and mailbox access, versus giving the agent its own address.
- [Give an OpenAI Agents SDK agent email](https://www.mailgi.xyz/openai-agents-sdk-email.html): three function tools (send, list, read) over the REST API, tested against the live API, wired into openai-agents.
- [Build a LangChain email agent](https://www.mailgi.xyz/langchain-email-agent.html): the same three tools wrapped for LangChain's create_agent; why not the Gmail toolkit.
- [Give a CrewAI agent email](https://www.mailgi.xyz/crewai-email-agent.html): Mailgi's hosted MCP server in the agent's mcps list via MCPServerHTTP, filtered to three mail tools; tested on CrewAI 1.15.
- [Give a Vercel AI SDK agent email](https://www.mailgi.xyz/vercel-ai-sdk-email.html): createMCPClient over Streamable HTTP, three mail tools passed to generateText or streamText; tested on ai 7.0.
- [Give an n8n AI agent email](https://www.mailgi.xyz/n8n-email-agent.html): No code: the MCP Client Tool node on an AI Agent, run on a schedule or from a Mailgi webhook.
- [Give your AI assistant its own email address](https://www.mailgi.xyz/ai-assistant-email-address.html): instead of your Gmail password: register, forward or CC what it needs, reply as itself.
- [Inbox per agent vs catch-all](https://www.mailgi.xyz/inbox-per-agent-vs-catch-all.html): isolation, credentials and prompt-injection exposure of a mailbox per agent versus one catch-all with a router; Mailgi has no catch-all.
- [Guides index](https://www.mailgi.xyz/guides.html): all guides in one place, ordered from first-time setup to specific use cases.
- [Receiving a verification code](https://www.mailgi.xyz/agent-email-verification.html): the full loop for an agent completing a signup that requires email confirmation — register, poll, extract the code — plus the four failure modes that make it flaky.
- [Running a support inbox](https://www.mailgi.xyz/agent-support-inbox.html): an agent on support@yourdomain.com reading, triaging, filing and answering; custom-domain setup, folders as ticket status, and why replies do not thread.
- [Agent-to-agent email](https://www.mailgi.xyz/agent-to-agent-email.html): two agents passing work over real addresses, free on @mailgi.xyz and counted on its own allowance, separate from the external send quota; loop prevention, and when to use a queue instead.
- [FAQ](https://www.mailgi.xyz/faq.html): 24 answers on registration, receiving verification codes, search and threading (not supported), sending limits, custom domains, pricing, top-ups, webhooks, MCP and data location.
- [Changelog](https://www.mailgi.xyz/changelog.html): dated, customer-facing releases, newest first — what the API supports as of each date.
- [Pricing](https://www.mailgi.xyz/pricing.html): receiving is free; mail leaving Mailgi is pay-as-you-go from a prepaid balance — every price and every sending limit, stated in full.

## Core concepts

- **Inbound webhooks**: `POST /v1/webhook-endpoints` registers an HTTPS URL; Mailgi POSTs a signed notification (`x-mailgi-signature`, HMAC-SHA256 hex over `timestamp.body`) when mail arrives: sender, recipients, time, size and a `fetchUrl`. No subject or content; read the message with the API key. Agent-scoped only — domain-scoped endpoints return 501 pending a privacy-policy change. Polling `GET /v1/mail` remains supported and is simpler. No WebSocket.
- **Agent registration**: `POST /v1/agents/register` — no OAuth, no signup form. Returns a friendly address (e.g. `buzzing-falcon@mailgi.xyz`) and an API key shown once.
- **Custom domains**: attaching a domain is dashboard-only and session-authenticated — not an API-key action. Once ownership is verified via DNS, Mailgi generates the full outbound record set for the human to publish: DKIM (BYODKIM — Mailgi generates and holds the keypair, published under Mailgi's own selector rather than an ESP-branded one), a dedicated MAIL FROM subdomain for SPF alignment, and a recommended DMARC record. Mailgi verifies each record as it goes live; sending is gated until the domain passes outbound verification.
- **Registration tokens**: an org admin creates a token in the dashboard (session-authenticated); an agent then self-registers a chosen address (e.g. `support@yourdomain.com`) on that domain by calling `POST /v1/agents/register` with `domainToken` and `localPart`.
- **Pricing**: pay-as-you-go from a prepaid balance, no subscription. Free: receiving mail from any sender, mail between your own agents (anything on `@mailgi.xyz`, and between your organisation's own domains), registration, custom domains, and the first 10 MB of storage per mailbox. Metered: $0.0005 per external recipient; $0.02 once, the first time an agent writes to an address that has never written to it (an address that writes first, with a valid DKIM signature, becomes a known contact for free); $0.25 per GB-month of storage above 10 MB. An agent registered on `@mailgi.xyz` has its own balance; agents on an organisation's domain share the organisation's. Anyone can top up any agent by card, with no account, at https://app.mailgi.xyz/topup (minimum $5, plus any sales tax or VAT; Stripe is the merchant of record). A send the balance cannot cover is refused whole with `402 PAYMENT_REQUIRED`, itemised, and nothing is charged.
- **Sending limits**: 100 per day per API key and 50 per hour / 300 per day per agent. Custom-domain orgs are capped by domain age, from 100 per day on a newly verified domain up to 5000 once established; agents on the shared @mailgi.xyz domain draw from one collective bucket of 500 per hour and 5000 per day. Mail to other @mailgi.xyz agents is counted separately: 1000 per hour and 5000 per day per agent. Inbound mail and reading an inbox are not limited.

## Optional

- CLI and TypeScript SDK: `npm install -g @mailgi/mailgi` or `npm install @mailgi/mailgi` (https://www.npmjs.com/package/@mailgi/mailgi). Not required — everything above works over plain HTTP.

- [About Mailgi](https://www.mailgi.xyz/about.html): why Mailgi exists, what it holds itself to, where it stands, and how to reach a person.
- [Security](https://www.mailgi.xyz/security.html): data location (including the US backup exception), hashed keys, DKIM/SPF/DMARC, signed content-free webhooks, abuse controls, and what is not in place yet (no SOC 2).

- [Privacy](https://www.mailgi.xyz/privacy.html): what is collected, where it is stored, the full sub-processor list, retention, and how to withdraw cookie consent. Mailbox content is stored in Germany and outbound relays through AWS in Ireland; Google is the only processor that sets cookies.

## Contact

- Support: hello@mailgi.xyz — a real inbox, hosted on Mailgi itself, read by a human.