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.
- Find it:
search_mail {"query": "from:priya newer_than:7d"}
{"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}]}
- Read how the owner edits drafts, so the first version is already close:
get_writing_feedback {}
- Draft the reply in the thread. Recipients, subject and quote come from the thread:
create_draft {"reply_to_thread_id": "t1", "body": "Hi Priya,\n\nThursday at 2pm ET works. See you then."}
{"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".
- Wait for them, without polling.
wait_for_reviewreturns the moment they act, or after up to 50 seconds; call it again to keep waiting:
wait_for_review {"review_ids": ["5PeEKSWTPMF_"], "timeout_seconds": 50}
{"decided": true, "items": [{"review_id": "5PeEKSWTPMF_", "status": "returned", "note": "Mention I'll send the agenda tomorrow."}]}
- Sent back: read the note and earlier versions, then replace the draft with the next version:
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.
draft_reply {"thread_id": "t1", "notes": "Yes to Thursday; agenda tomorrow"}
{"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:
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 #
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:
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 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:
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"}
]
}
{"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):
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 #
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:
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 #
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:
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 #
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 #
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 #
list_accounts {}
{"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:
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.