Angel Mail Docs

Troubleshooting

The agent says Angel Mail isn't connected #

  • Claude Code: run /mcp, pick angel-mail and choose Authenticate. claude mcp list should show it as connected.
  • Codex: codex mcp login angel-mail.
  • Gemini CLI: /mcp auth angel-mail.
  • An app with a token: check the header is exactly Authorization: Bearer smt_… and the token wasn't revoked (Settings → AI connections).
  • Two entries: an older sterling-mail entry next to angel-mail can confuse an agent. Remove the old one (claude mcp remove --scope user sterling-mail, codex mcp remove sterling-mail).

"This app isn't registered with Angel Mail" #

The sign-in started from somewhere Angel Mail didn't register, often a stale client. Start the connection again from the app itself (Claude, ChatGPT, Grok, Cursor, VS Code). Any other app connects with a token from Settings → AI connections → Any other MCP client.

"Angel Mail connects by sign-in only to …" #

The app asked to return somewhere other than a known app or this computer. If someone sent you the link, close the page. Otherwise use a token.

403: the owner turned it off #

The owner switched this agent off in Settings → AI connections. Tell them; it works again once they switch it back on. Don't start a new sign-in, which won't help.

429: too many requests #

Wait the number of seconds in Retry-After. If you are checking whether the owner has acted, use wait_for_review instead of calling in a loop.

"None of these are your queue items" or "No such item among yours" #

Each token sees only its own items in Agent drafts. A different token, or the same agent connected twice under different names, won't find the other's drafts. list_my_drafts shows yours.

send_approved_email isn't there #

It is listed only for tokens the owner marked Can send. Without it, give the owner the review_url: they press Send in Agent drafts.

"This request is over 2 hours old" #

send_approved_email works within 2 hours of the request_send. Make a new request_send, show the owner the preview again and get their yes.

A skill answer was refused ("Not saved: …") #

The error names what the check found: an item for a conversation that wasn't in the material, two items for one conversation, unsubscribe where the sender doesn't offer it, a field missing from the schema. Fix that and call again with the same ticket. A ticket older than 2 hours, or from another inbox or token, is refused: start again with the first call.

sort_conversations returns nothing #

There is no new, unhandled mail in the Inbox since the last pass, or (with only_due: true) the inbox isn't set to be sorted by an agent or isn't due yet.

An attachment fails #

25 MB in total per email. A request stops at about 4 MB, so content_base64 is only for small files: put anything bigger at a public https URL and pass url. Private addresses and plain http are refused.

The wrong inbox #

Pass account (from list_accounts) to every tool in the job. Without it, the primary inbox is used.

For agents: this page as Markdown, every page in one file at llms-full.txt, the index at llms.txt.