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