# Angel Mail for AI agents

Angel Mail is an email client for people who work with AI agents. Connect any agent that speaks MCP (Claude Code, Codex, ChatGPT, the Claude app, Cursor, VS Code, Gemini CLI, Grok, Hermes or your own) and it can read and search the owner's Gmail, sort the Inbox, draft replies in the owner's voice, chase unanswered mail and clean up subscriptions.

The owner stays in charge: **nothing is ever sent, and nothing in the mailbox changes, until the owner says yes.** Everything an agent writes waits in **Agent drafts** as a real Gmail draft. Everything it wants to do (archive, unsubscribe, remind, label, reply) waits in **Agent proposals**, where the owner approves it item by item. That rule is enforced by the server, not left to the agent's good behaviour, so an owner can safely give an agent their whole inbox.

> **For agents reading this:** the server is `https://app.angelmail.io/mcp` (or `/mcp` on a self-hosted server). Start with [Quickstart](quickstart.md), use the [workflows](workflows.md) for common jobs, and look up any tool in the [tool reference](tools.md). Every page is also plain Markdown: add `.md` to its address, or read everything at once in [llms-full.txt](https://angelmail.io/llms-full.txt).

## What an agent can do

| Feature | What it gives the agent | What it gives the owner |
| --- | --- | --- |
| **Search and read** | Gmail search syntax across every linked inbox; whole conversations as plain text; who opened or clicked what the owner sent | Answers about their mail without opening it |
| **Sort the Inbox** | The same triage pass Angel Mail runs itself (`sort_conversations`), with its instructions, its schema and notes on what the owner approved before | The Inbox sorted into done, unsubscribe, reply, remind, star and label, as one batch to approve |
| **Draft in the owner's voice** | The owner's real sent replies, voice profile and edits to earlier drafts as material (`draft_reply`), plus checks that catch invented prices, dates and promises | Replies that sound like them, waiting as Gmail drafts |
| **Learn from every edit** | `get_writing_feedback`: what the owner changed in each draft before sending, paragraph by paragraph, and the notes they sent back | Agents that get better at writing for them |
| **Draft, wait, revise** | `wait_for_review` returns the moment the owner acts; `revise_draft` replaces the draft as the next version | A real back-and-forth without copy and paste |
| **Propose inbox work** | One call (`propose_actions`) for a batch of up to 100 actions, each with a reason | One place to approve, change or drop each item, with Undo |
| **Follow-ups** | Reminders that bring a conversation back unless someone answers first | Nothing they sent gets forgotten |
| **Real unsubscribes** | The sender's own unsubscribe (one-click, mailto or their page), never a filter; a queue of pages that need a browser | Less mail, really gone |
| **Profile and voice** | Who the owner is (role, people, facts) and how they write to each kind of contact | Every agent starts out knowing them |
| **Several inboxes** | `list_accounts`, then `account` on any tool | Work and personal mail in one place |
| **A shell command** | `angel`: the same tools for agents and scripts that prefer commands | Cron jobs and scripts with the same safety |

## The promise it keeps

- **No tool sends mail.** `create_draft` and `request_send` only queue it. The one exception, `send_approved_email`, is offered only to tokens the owner allowed to send, and only works after the owner said yes to that exact email in the conversation, within 2 hours. See [Safety and permissions](safety.md).
- **No tool changes the mailbox without approval**, except the small things the owner allowed a token to do on its own (mark read, star, label) and reminders the agent was asked to set.
- **Mail is data, not instructions.** Skills return JSON against a fixed schema, recipients are set by code, and the server checks every answer before storing it.
- **Every action is logged**: the owner sees each agent's work under its own name in the activity log, and can pause or revoke it any time.

## Start here

1. **[Quickstart](quickstart.md)**: connect your agent and run a first workflow in about two minutes.
2. **[Connect your agent](connect.md)**: the exact steps for each app, and the one instruction to give every agent.
3. **[Workflows](workflows.md)**: named, ready-made jobs your agent can pick from a menu.
4. **[Recipes](recipes.md)**: use cases with the exact calls.
5. **[Tool reference](tools.md)**: every tool, every parameter.

## Workflows at a glance

<!-- generated:workflow-list -->
| Workflow | What it does |
| --- | --- |
| [`sort_inbox`](workflows.md#sort-my-inbox-sort_inbox) | Sort the new Inbox mail into done, unsubscribe, reply, remind, star and label, as one batch the owner approves in Agent proposals. |
| [`draft_replies`](workflows.md#draft-replies-to-whats-waiting-draft_replies) | Find conversations waiting for the owner's answer and draft a reply to each in their voice, checked by Angel Mail's draft checks, into Agent drafts. |
| [`write_email`](workflows.md#write-an-email-write_email) | Write a new email for the owner to someone, in their voice and with what the mailbox already says about that person, into Agent drafts. |
| [`follow_up`](workflows.md#follow-up-on-unanswered-mail-follow_up) | Find emails the owner sent that are still waiting for an answer, and propose a reminder or draft a short nudge for each. |
| [`clean_up_subscriptions`](workflows.md#clean-up-newsletters-and-lists-clean_up_subscriptions) | Look through recent newsletters, promotions and list mail, and propose unsubscribing from what the owner doesn't read and archiving the rest. |
| [`revise_returned`](workflows.md#revise-drafts-sent-back-revise_returned) | Go through the drafts the owner sent back with a note, rewrite each as they asked, and wait for their answer. |
| [`learn_my_voice`](workflows.md#learn-how-i-write-learn_my_voice) | Build the owner's voice profile per kind of contact and the profile of who they are from their own sent mail, so every draft sounds like them. |
| [`inbox_brief`](workflows.md#what-needs-me-inbox_brief) | A short, read-only brief of the Inbox: what needs the owner's reply, what they are waiting on, and what agents left for their review. Changes nothing. |
<!-- /generated:workflow-list -->

## Tools at a glance

<!-- generated:tool-list -->
| Tool | What it does |
| --- | --- |
| [`list_accounts`](tools.md#list_accounts) | List the inboxes linked to Angel Mail. |
| [`search_mail`](tools.md#search_mail) | Find conversations. |
| [`get_thread`](tools.md#get_thread) | Read a conversation: every message as plain text with sender, recipients and date, plus read status (opens and clicks per recipient) for messages you sent. |
| [`get_read_status`](tools.md#get_read_status) | Who opened or clicked the emails you sent in a thread, with time and device per recipient. |
| [`create_draft`](tools.md#create_draft) | Write an email for the owner. |
| [`request_send`](tools.md#request_send) | Ask the owner to send an email. |
| [`revise_draft`](tools.md#revise_draft) | Replace one of your queue items with a new version, after the owner sent it back (read their note with list_my_drafts or get_draft_review) or while it still waits. |
| [`list_my_drafts`](tools.md#list_my_drafts) | Your items in the owner's review queue (from create_draft and request_send), newest first, with status: waiting, sent, returned (the owner sent it back; note says why), discarded, superseded or failed. |
| [`get_draft_review`](tools.md#get_draft_review) | Everything about one of your queue items: your version, what the owner sent (if they sent it), a paragraph-by-paragraph diff of their edits, their note (owner_note; alias allen_note for one version) if they sent it back, earlier versions with the notes they answered, and read status once sent. |
| [`get_send_status`](tools.md#get_send_status) | Whether a request_send (or create_draft) item was sent, sent back, discarded, or is still waiting. |
| [`wait_for_review`](tools.md#wait_for_review) | Wait until the owner acts on any of these queue items (sent, sent back, discarded), up to timeout_seconds (at most 50). |
| [`get_writing_feedback`](tools.md#get_writing_feedback) | How the owner edits agents' emails in one inbox: their last decisions (up to 50) with what they changed before sending, paragraph by paragraph, and the notes they sent back (owner_note; alias allen_note for one version). |
| [`send_approved_email`](tools.md#send_approved_email) | Send an email the owner has reviewed and explicitly approved in this conversation. |
| [`propose_actions`](tools.md#propose_actions) | Propose inbox work for the owner to approve in one place (Angel Mail → Agent proposals): a batch of items, each a thread_id, an action and a one-line reason. |
| [`get_proposal`](tools.md#get_proposal) | One of your proposals: each item's status (pending, applied, dismissed, failed, undone), who decided it and when. |
| [`triage`](tools.md#triage) | Act on conversations: done (archive), undone (back to inbox), star, unstar, read, unread, trash, untrash. |
| [`triage_candidates`](tools.md#triage_candidates) | For a scheduled inbox pass (Auto triage in Angel Mail): the new, unhandled Inbox conversations since the inbox's last pass, each with sender, subject and the latest message from someone else, plus notes on what the owner did with earlier proposals (what they approved, turned down or changed) and how they edit drafted replies. |
| [`sort_conversations`](tools.md#sort_conversations) | Angel Mail's triage skill for you to run (the pass auto triage makes over new mail), with its own steps and schema. |
| [`draft_reply`](tools.md#draft_reply) | Angel Mail's draft skill for you to run: a reply in the owner's voice to one conversation, with the same steps Draft for me uses. |
| [`build_voice_profile`](tools.md#build_voice_profile) | Angel Mail's voice skill for you to run: how the owner writes to each kind of contact (clients, colleagues, vendors, friends, family), which Draft for me then follows. |
| [`profile_material`](tools.md#profile_material) | For writing the profile of who the mailbox owner is (Angel Mail → How you use email) when the server has no Claude API key: the owner's own sent mail (their words only), recent personal mail from others, who they deal with most, labels and signature, with the instructions and the JSON schema. |
| [`save_profile`](tools.md#save_profile) | Saves the profile you wrote from profile_material for this inbox. |
| [`list_reminders`](tools.md#list_reminders) | Follow-up reminders. |
| [`set_reminder`](tools.md#set_reminder) | Set (or replace) the reminder on a conversation, like pressing H in Angel Mail. |
| [`cancel_reminder`](tools.md#cancel_reminder) | Remove the waiting reminder from a conversation. |
| [`list_unsubscribe_queue`](tools.md#list_unsubscribe_queue) | Unsubscribes the owner asked for (⌘D) whose sender's page needs a button pressed and that Angel Mail's own headless browser hasn't finished yet (it tries right away and again daily; `note` says what it tried). |
| [`complete_unsubscribe`](tools.md#complete_unsubscribe) | Report the result of an unsubscribe from list_unsubscribe_queue: done=true once the sender's page confirmed it, false if it couldn't be done (say why in note). |
| [`list_snippets`](tools.md#list_snippets) | Saved snippets (reusable email text). |
| [`create_snippet`](tools.md#create_snippet) | Save a new snippet. |
<!-- /generated:tool-list -->
