Mailgi
Email for AI agents. Every agent gets a real, deliverable mailbox and uses it entirely over REST — no SMTP or IMAP client required.
An agent registers itself with one unauthenticated POST and gets an address it
can receive verification codes on, reply from and keep mail in. Receiving is
free; mail to the outside world is pay-as-you-go. Also available as a hosted
MCP server at https://api.mailgi.xyz/mcp.
- Website: https://www.mailgi.xyz
- Guides: https://www.mailgi.xyz/guides.html (verification codes, support inbox, OpenAI Agents SDK, LangChain)
- Docs: https://www.mailgi.xyz/docs.html
- API docs: https://api.mailgi.xyz/docs
- Agent-readable reference: https://www.mailgi.xyz/SKILL.md
This repository
| Path | What | Status |
|---|---|---|
packages/typescript | TypeScript SDK + mailgi CLI — npm @mailgi/mailgi | published |
packages/python | Python SDK — PyPI mailgi | planned |
apps/ui | React developer UI for inspecting mailboxes | dev tool |
spec | openapi.json — the contract every SDK targets | — |
The API and mail infrastructure live in a separate private repository.
Quick start
npm install -g @mailgi/mailgi
mailgi register --label my-agent # saves to ~/.mailgi/config.json
mailgi send --agent <handle> --to alice@example.com --subject Hi --body Hello
mailgi inbox --agent <handle>
Or from code:
import { AgentMailboxClient } from "@mailgi/mailgi";
const client = AgentMailboxClient.withApiKey("https://api.mailgi.xyz", process.env.MAILGI_API_KEY!);
await client.sendMail({ to: ["alice@example.com"], subject: "Hi", textBody: "Hello" });
MCP server
Mailgi runs a hosted MCP server (Streamable HTTP) at https://api.mailgi.xyz/mcp,
1:1 with the REST API. No API key is needed to start: the agent calls
register_agent and gets its own address and key.
claude mcp add --transport http mailgi https://api.mailgi.xyz/mcp
Setup for Cursor, Claude Desktop and other clients: https://www.mailgi.xyz/mcp.html.
server.json is the entry in the official MCP Registry as xyz.mailgi/mailgi.
Working on this repo
npm install # installs all workspaces
npm run build # builds every package
npm test # runs every package's tests
npm run dev -w @mailgi/ui # developer UI on :5173
Workspaces are listed explicitly in the root package.json rather than globbed,
so non-Node packages such as packages/python can sit alongside them without
confusing npm.
Release tags are namespaced per package — ts-sdk-v0.2.0, py-sdk-v0.1.0 —
because the SDKs version independently.
License
MIT