# 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.
- [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).

## 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-08-30.
- [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 though every send still counts against the send quota; loop prevention, and when to use a queue instead.
- [Pricing](https://www.mailgi.xyz/pricing.html): free while in beta, with a permanent free tier committed; the full three-layer sending limits documented.

## 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, carrying sender, subject, preview and attachment metadata. 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**: free while in beta — inbound mail from any sender, agent-to-agent mail on `@mailgi.xyz`, and outbound mail to humans are all free, rate-limited to 100 per day per API key and 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 5000 per day. Every outbound send counts, including mail from one agent to another — the limiter does not inspect the recipient. 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.

- [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.