# Recipes

Use cases with the exact calls. Each call is shown as the tool's name and its JSON arguments; results are cut down to the fields that matter. Replies and IDs come from the demo mailbox.

## Reply to an email, and revise after the owner's note

The loop most agents use: find the email, draft the reply, wait for the owner, revise if they send it back.

1. Find it:

```json
search_mail {"query": "from:priya newer_than:7d"}
```

```json
{"threads": [{"thread_id": "t1", "subject": "Q4 planning call", "participants": ["Priya Shah <priya@northwind.example>"],
  "snippet": "Can we move our planning call to Thursday at 2pm ET? …", "unread": true}]}
```

2. Read how the owner edits drafts, so the first version is already close:

```json
get_writing_feedback {}
```

3. Draft the reply in the thread. Recipients, subject and quote come from the thread:

```json
create_draft {"reply_to_thread_id": "t1", "body": "Hi Priya,\n\nThursday at 2pm ET works. See you then."}
```

```json
{"status": "waiting", "review_id": "5PeEKSWTPMF_", "review_url": "https://app.angelmail.io/?review=5PeEKSWTPMF_",
 "to": ["priya@northwind.example"], "subject": "Re: Q4 planning call",
 "note": "Not sent. It is waiting in the owner's Angel Mail review queue (Agent drafts); tell them so and give them review_url."}
```

Tell the owner it is in Agent drafts and give them the `review_url`. Use `request_send` instead of `create_draft` when the email is ready to go as written: it shows as "Wants to send".

4. Wait for them, without polling. `wait_for_review` returns the moment they act, or after up to 50 seconds; call it again to keep waiting:

```json
wait_for_review {"review_ids": ["5PeEKSWTPMF_"], "timeout_seconds": 50}
```

```json
{"decided": true, "items": [{"review_id": "5PeEKSWTPMF_", "status": "returned", "note": "Mention I'll send the agenda tomorrow."}]}
```

5. Sent back: read the note and earlier versions, then replace the draft with the next version:

```json
get_draft_review {"review_id": "5PeEKSWTPMF_"}
revise_draft {"review_id": "5PeEKSWTPMF_", "reply_to_thread_id": "t1",
  "body": "Hi Priya,\n\nThursday at 2pm ET works. I'll send the agenda tomorrow."}
```

When they send it, `get_draft_review` shows what they changed (`owner_changed`, and a paragraph-by-paragraph `diff`), which `get_writing_feedback` also collects for next time.

## Draft in the owner's voice with the draft skill

`draft_reply` runs Angel Mail's own Draft for me steps: the server gathers the material (the conversation, real emails the owner sent to this person and people like them, their voice file and profile), the agent writes, and the server checks the answer before it becomes a draft.

```json
draft_reply {"thread_id": "t1", "notes": "Yes to Thursday; agenda tomorrow"}
```

```json
{"tool": "draft_reply", "skill": "draft", "version": "draft.2", "instructions": "…", "material": "…",
 "schema": {"type": "object", "properties": {"body": …, "unsure": …}}, "ticket": "v1.s0.…",
 "next": "Write the answer exactly as the instructions say … Then call draft_reply again with account, answer (that object) and ticket."}
```

Write the answer as the instructions say, then:

```json
draft_reply {"thread_id": "t1", "ticket": "v1.s0.…", "answer": {"body": "Hi Priya,\n\nThursday at 2pm ET works …", "unsure": []}}
```

The checks fix line breaks, take out markdown and an invented signature, and turn prices, dates, links, names and promises the conversation doesn't support into `[placeholders]`, listed in `unsure`. The reply then lands in Agent drafts exactly like `create_draft`. A ticket is good for 2 hours and only for the tool, inbox and token that got it.

## Sort the Inbox

```json
sort_conversations {}
```

returns the new, unhandled Inbox conversations with the triage instructions, notes on what the owner approved or turned down before, the schema and a ticket. Decide each one, then:

```json
sort_conversations {"ticket": "…", "answer": {"summary": "One invite filed, one reply drafted.", "items": [
  {"thread_id": "t12", "action": "done", "reason": "Calendar invite, already on the calendar", "when": "", "label": "", "body": ""},
  {"thread_id": "t1", "action": "reply", "reason": "Priya asked to move the call", "when": "", "label": "", "body": "Thursday at 2pm ET works."}
]}}
```

Every item has all six fields (empty strings where they don't apply), as the schema in the material says. The server checks it (only these conversations, one item each, unsubscribe only where the sender offers it) and puts it in Agent proposals as an Auto triage batch. The `sort_inbox` [workflow](workflows.md) walks an agent through exactly this.

## Propose your own batch

For inbox work you decided yourself, `propose_actions` takes up to 100 items, each with a reason:

```json
propose_actions {
  "title": "Newsletters you never open",
  "rationale": "Six senders, none opened in 30 days.",
  "items": [
    {"thread_id": "t31", "action": "unsubscribe", "reason": "8 emails in 30 days, all unread"},
    {"thread_id": "t32", "action": "done", "reason": "Shipping notice, delivered"},
    {"thread_id": "t33", "action": "remind", "when": "monday 9am", "condition": "if_no_reply", "reason": "Waiting on the signed contract"},
    {"thread_id": "t34", "action": "label", "label": "Receipts", "reason": "Invoice"},
    {"thread_id": "t35", "action": "reply", "body": "Thanks, got it.", "reason": "Asked to confirm receipt"}
  ]
}
```

```json
{"proposal_id": "8CFcxKY1h8Sn", "review_url": "https://app.angelmail.io/?proposal=8CFcxKY1h8Sn", "status": "open",
 "items": [{"item_id": "bCVi2q2QEOI", "thread_id": "t31", "action": "unsubscribe", "status": "pending"}, …]}
```

The owner can switch items off, change them or remove them, then approve. `get_proposal` shows what happened to each (`applied`, `dismissed`, `failed`, `undone`). Approved replies become drafts in Agent drafts; nothing is sent.

## A scheduled inbox pass

When the owner sets Agent proposals → Auto triage… to an agent, Angel Mail expects an agent to sort the inbox when it is due. Run this on a schedule (cron, a LaunchAgent, your agent's own scheduler):

```json
sort_conversations {"only_due": true}
```

It returns nothing unless the inbox is due, and takes the inbox so no other agent sorts it at the same time. Then answer as above. The older pair `triage_candidates` + `propose_actions` with `auto_run: true` does the same.

## Follow up on what nobody answered

```json
list_reminders {}
search_mail {"query": "in:sent newer_than:14d", "limit": 40}
get_thread {"thread_id": "t20"}
```

Keep the conversations where the owner wrote last, asked for something, and nobody answered. Then either set a reminder at once, the way pressing H does:

```json
set_reminder {"thread_id": "t20", "when": "tuesday 9am", "condition": "if_no_reply"}
```

or propose it (`propose_actions` with `"action": "remind"`) when the owner should decide. Sent emails that ask for an answer already get an automatic reminder (2 weekdays at 8:00 AM, if no reply). The `follow_up` workflow does all of this.

## Clean up subscriptions

```json
search_mail {"query": "(category:promotions OR unsubscribe) newer_than:30d -in:sent", "limit": 40}
```

Group by sender, count what is unread, and propose `unsubscribe` for senders the owner plainly doesn't read. Angel Mail's unsubscribe is real: the sender's one-click unsubscribe, then their mailto address, then their page, pressed by a headless browser. Pages it can't finish wait in a queue for an agent with a browser:

```json
list_unsubscribe_queue {}
complete_unsubscribe {"id": "u7", "done": true}
```

Never sign in, make an account, give other personal details or pay on such a page; report it as not done with a `note`.

## Learn who the owner is and how they write

```json
build_voice_profile {}                         → material + ticket
build_voice_profile {"answer": {…}, "ticket": "…"}
profile_material {}                            → material, instructions, schema
save_profile {"profile": {…}, "emails_read": 200}
```

The voice profile says how the owner writes to each kind of contact (clients, colleagues, vendors, friends, family); the profile says who they are, who they deal with most, and facts drafts may use. Both change no mail, and the owner can read and correct them in Angel Mail → How you use email. Every later draft and triage pass uses them.

## Attach files

```json
create_draft {"to": ["Jordan <jordan@example.com>"], "subject": "Deck", "body": "Here's the deck.",
  "attachments": [{"filename": "deck.pdf", "url": "https://example.com/files/deck.pdf"},
                  {"filename": "notes.txt", "content_base64": "SGVsbG8="}]}
```

25 MB in total (Gmail's limit). `url` must be public https (the server downloads it); `content_base64` only for small files, because a request stops at about 4 MB.

## Several inboxes

```json
list_accounts {}
```

```json
{"accounts": [{"email": "alex@example.com", "primary": true}, {"email": "alex@morganreed.example"}]}
```

Pass `account` to any tool to work in that inbox; without it, the primary inbox is used. If it isn't clear which inbox an email should come from, ask the owner.

## Send after the owner's yes in the chat

Only for tokens the owner marked **Can send**. Show the full `preview` that `request_send` returns, get an explicit yes for that exact email, then:

```json
request_send {"to": ["jordan@example.com"], "subject": "Friday", "body": "Friday at 10 works."}
send_approved_email {"request_id": "Hk2…", "owner_approved": true}
```

It sends the frozen request exactly as previewed, within 2 hours. To change anything, make a new `request_send`. Without Can send, the owner presses Send in Agent drafts.
