Quickstart
Connect an agent to Angel Mail and run a first workflow. It takes about two minutes. You need an Angel Mail account with Gmail linked, either at app.angelmail.io or on your own server.
1. Add the server #
The MCP server is:
https://app.angelmail.io/mcp
On your own server it is https://<your server>/mcp. Most apps connect by signing in once: you approve a page from Angel Mail, and the app keeps the connection. Pick yours:
| Your agent | Do this |
|---|---|
| Claude Code | claude mcp add --scope user --transport http angel-mail https://app.angelmail.io/mcp, then /mcp → angel-mail → Authenticate |
| Codex | codex mcp add angel-mail --url https://app.angelmail.io/mcp, then codex mcp login angel-mail |
| Claude app (claude.ai, desktop, phone) | Settings → Connectors → Add custom connector, paste the URL, Connect |
| ChatGPT | Settings → Apps & Connectors → Advanced → Developer mode → create a connector with the URL, OAuth, Connect |
| Cursor | Add {"mcpServers": {"angel-mail": {"url": "https://app.angelmail.io/mcp"}}} to ~/.cursor/mcp.json, then Connect |
| VS Code | code --add-mcp '{"name":"angel-mail","type":"http","url":"https://app.angelmail.io/mcp"}', then start it and sign in |
| Gemini CLI | gemini mcp add --scope user --transport http angel-mail https://app.angelmail.io/mcp, then /mcp auth angel-mail |
| Anything else | Make a token in Angel Mail → Settings → AI connections → Any other MCP client, and send Authorization: Bearer smt_… |
Connect your agent has the full steps for each, including Grok, Hermes, Uriel, the plugins and the shell command.
2. Give your agent the rule #
Put this in your agent's own instructions (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, Cursor's rules…), so it never reaches for another mail tool. Angel Mail → Settings → AI connections shows it with your name filled in.
Email for the owner goes through Angel Mail (MCP server `angel-mail` (older setups: `sterling-mail`), or the `angel` command (older installs: `sterling`) where installed). To draft, reply to or send email for them, use its create_draft or request_send (revise_draft after they send one back). Never draft or send through Gmail, gog, Composio, Himalaya, Apple Mail or any other mail tool, even if one is available. Everything you write waits in Angel Mail → Agent drafts until the owner sends it; tell them it is there and give them the review_url. If Angel Mail isn't connected in this session, say so and stop rather than using another mail tool.
3. Check it works #
Ask your agent:
Which inboxes can you see in Angel Mail?
It should call list_accounts and name your inbox. If it says it isn't connected, see Troubleshooting.
4. Run a workflow #
Workflows are ready-made jobs your agent can pick from a menu. In Claude Code, type / and pick mcp__angel-mail__sort_inbox; in other apps look for prompts in the MCP or attachment menu, or just ask:
Use the sort_inbox workflow in Angel Mail.
The agent reads the new Inbox mail with sort_conversations, decides each conversation, and sends one batch to Agent proposals. Open Angel Mail, look through the batch, switch off anything you don't want, and press Approve. Replies it drafted wait in Agent drafts until you press Send.
Try these next:
| Ask your agent | Workflow |
|---|---|
| "Draft replies to the mail that's waiting for me." | draft_replies |
| "Write to Jordan that we're moving Thursday's call to Friday." | write_email |
| "What did I send last week that nobody answered?" | follow_up |
| "Clean up the newsletters I never read." | clean_up_subscriptions |
| "Learn how I write." | learn_my_voice |
| "What needs me today?" | inbox_brief |
See Workflows for what each one does, step by step.
5. Try it without your own mail #
A local server in demo mode has a made-up mailbox and lets an agent connect without signing in:
git clone https://github.com/PirateKing44/Angel-Mail && cd Angel-Mail && npm ci
DEMO_MODE=1 npx next dev -p 3400
claude mcp add --transport http angel-mail-demo http://localhost:3400/mcp
Everything works there, including sending, which only goes to the demo mailbox.