How it works
The ideas behind the tools. Knowing them, an agent can work out the right call for jobs no recipe covers.
The owner, inboxes and accounts #
Everything an agent does runs as the owner: the person who connected it. Tool descriptions, notes and errors name them (their first name, or what they set in Angel Mail) and then say they/them.
An owner can link several Gmail or Google Workspace inboxes. list_accounts lists them; every tool takes account (the inbox's address) and defaults to the primary one. Threads, drafts and reminders belong to one inbox, so pass the same account through a job.
The review queue: Agent drafts #
Everything an agent writes becomes an item in Agent drafts, backed by a real Gmail draft labelled with the agent's name. The owner reads it, edits it, sends it, sends it back with a note, or discards it.
| Status | Meaning |
|---|---|
waiting | In the queue. From request_send it shows as "Wants to send" |
sent | The owner sent it. owner_changed says what they changed first |
returned | Sent back with a note (owner_note): revise it with revise_draft |
discarded | The owner threw it away |
superseded | Replaced by a newer version or request |
failed | Sending failed; the reason is on the item |
sent_elsewhere means the owner sent or deleted the Gmail draft outside Angel Mail. create_draft is for email that needs the owner's touch, request_send for email ready to go; request_send with a draft_id turns your earlier draft into a send request, as the same item. Each item has a review_url that opens it in Angel Mail; always give it to the owner.
Versions. revise_draft replaces the Gmail draft and puts the item back to waiting as the next version, with the owner's earlier notes kept in its history. The owner sees "revised after your note".
Learning from edits. When the owner sends an item, Angel Mail keeps what they changed, paragraph by paragraph. get_draft_review shows it for one item; get_writing_feedback shows the last 50 decisions in an inbox, so an agent can match how the owner writes before it starts.
Proposals: Agent proposals #
Inbox work an agent wants done arrives as a proposal: a batch of items, each one conversation, one action and a one-line reason.
| Action | What approving does |
|---|---|
done / undone | Archive / back to the Inbox |
trash / untrash | Move to / out of Trash (always needs approval) |
star / unstar, read / unread | As named |
label | Add the label named in label |
remind | Set a reminder: when ("tuesday 9am", "3 days", "someday" or ISO), condition if_no_reply or regardless |
unsubscribe | Angel Mail's real unsubscribe, the way the sender offers it; also archives |
reply | Saves body as a reply draft in Agent drafts (never sends) |
draft_reply | Links a reply you already made with create_draft (review_id) |
The owner can switch each item on or off, change it or remove it, then approve: "Approve 7 of 12". Applied items can be undone from Agent proposals. Item statuses: pending, applied, dismissed, failed, undone, expired. Open batches expire after 7 days, and items whose conversation already left the Inbox expire too.
Done at once. If the owner allowed the token to do some things on its own (mark read, star, label), those items are applied at once and the rest wait. triage is the quick form: one action for several conversations, done at once where allowed, otherwise a proposal.
Skills and tickets #
Angel Mail's own AI jobs are skills: sorting the Inbox (sort_conversations), drafting a reply (draft_reply), the voice profile (build_voice_profile). Angel Mail can run them on its own models, on a worker, or hand them to an agent. As MCP tools they work in two calls:
- Material. The first call returns what the skill needs, gathered by the server exactly as its own runner would: the instructions, the material (emails, notes, examples), the JSON schema of the answer, the prompt version and a ticket.
- Answer. The second call sends
answer(one JSON object matching the schema) and the ticket. The server runs the skill's own checks and stores the result where the skill's runner would: an Auto triage batch, the voice profile, an Agent draft.
A ticket is sealed by the server and good for 2 hours, for that tool, inbox, token and prompt version. A refused answer comes back as an error that names what to fix; fix it and send it again with the same ticket. Pass model (what you are running on) to label the result.
The profile and the voice #
Two things make drafts sound like the owner:
- The profile (
profile_materialโsave_profile): who the owner is, their role, the people they deal with most, facts a draft may use, their style. Written from their own sent mail. - The voice profile (
build_voice_profile): how they write to each kind of contact (clients, colleagues, vendors, friends, family), with examples taken from their mail and the changes they made to drafts. Rebuilt weekly once the owner switches it on in Settings โ AI connections, or whenever an agent builds it.
Both change no mail, and the owner reads and corrects them in Angel Mail โ How you use email. draft_reply and Angel Mail's own Draft for me use both, along with the owner's real sent replies to similar mail.
Draft checks #
Every draft written through the draft skill is checked before the owner sees it: line breaks and greetings put right, markdown and invented signatures taken out, and any price, percentage, date, time, length of time, link, address, phone number, name or promise that the conversation, the owner's notes or their profile don't support turned into a [placeholder] and listed in unsure. Tell the owner what is in unsure.
Reminders #
A reminder brings a conversation back at a time, unread, unless someone else answered first (if_no_reply), or regardless. "If no reply" reminders go to the Follow up folder, the others to the Inbox. Sent emails that ask for an answer get one by themselves (by default 2 weekdays, 8:00 AM, if no reply). set_reminder and cancel_reminder act at once, like the H key; a remind item in a proposal waits for approval.
Read status #
Emails the owner sends through Angel Mail are tracked unless they turn it off: each recipient gets their own copy, so opens and clicks are counted per person. get_read_status and get_thread show them, and search_mail shows the totals on conversations where the owner wrote last.
Unsubscribing #
Angel Mail unsubscribes the way the sender offers it: the one-click unsubscribe (RFC 8058), then the mailto address, then the sender's page, where a headless browser presses only the sender's own unsubscribe or confirm button. It never adds a filter. Pages it can't finish wait in list_unsubscribe_queue for an agent with a browser.
Workers #
An always-on computer of the owner's (a Mac mini, a server) can run angel worker and do Angel Mail's AI jobs with Claude Code or Codex on the owner's own plan: Draft for me from the phone, the profile, triage. A worker has its own kind of token (smw_) that can only take jobs and answer them: it can't call MCP tools, read mail beyond the job or send. Agents don't need a worker; it is how Angel Mail runs skills by itself when the owner has no API key.
Snippets #
Reusable email text the owner keeps (list_snippets, create_snippet). Variables {first_name}, {last_name}, {name} and {email} fill from the first recipient when used in Angel Mail.