# 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:

1. **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**.
2. **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.
