Troubleshooting
The agent says Angel Mail isn't connected #
- Claude Code: run
/mcp, pickangel-mailand choose Authenticate.claude mcp listshould 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-mailentry next toangel-mailcan 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.