cherami.

Troubleshooting and FAQ

Fix access problems, missing mail, refused inboxes and sends, and unexpected search results.

Read as Markdown ↗

Setting up a client or missing tools? Start with MCP troubleshooting.

Access

What if my API key is lost or revoked?

Create a new key in Account → API keys, or, for an agent, have its human choose Get the message on the Account home. A new key doesn't disable the old one: if the old key may have been exposed, revoke it on the API keys page.

Should I use an API key or reconnect with OAuth?

Use OAuth for an MCP client that supports it. Use an API key for the HTTP API, the SDKs, or an MCP client configured with a key. The six-word phrase isn't a key; exchange it for one first.

Why can't a connected client see my mail?

Ask the client to list your inboxes. If that fails, it found Cherami's tools without access to your account: follow the MCP connection diagnostics.

Inboxes

Why can't I create an inbox?

409 address_unavailable: that address is taken, reserved or retired. Choose another prefix.

409 inbox_limit_reached: every inbox slot on the account is in use. Use an inbox the account already has, delete one you no longer need (its mail goes with it and its address is retired for good), or ask for more.

Receiving

Why has an expected email not appeared?

Check that you're listing the inbox whose address the sender used, with no text, sender or recipient filters, and ask the sender to confirm the address they wrote to. Then check the inbox's receiving rules: mail from a blocked address or domain does not arrive, and no copy exists. For other listing problems, see missing messages.

Why can I see a message but not read its content?

Its content is readable once processing_status is ready; for pending or processing, check again shortly. For failed, the raw message is still available: see waiting for content.

Does Cherami provide webhooks?

Yes, and they're how an agent can react to mail as it arrives: mail itself doesn't start your agent. Add a webhook and we call your https URL when received mail is ready or a send is accepted; your server, function or automation then starts the agent, which fetches the message through the API. Without a webhook, have the agent check for mail when it runs (Receive and poll for mail). The cookbooks have runnable examples.

Why did my receiver get nothing?

Open Account → Webhooks or list webhook events. No event for the message means the mail isn't ready yet or the send wasn't accepted. An event shows each attempt and what your receiver answered (get an event); an event with no attempt for your webhook means its inboxes or events don't include this one. A webhook stops receiving while it's disabled, whether you switched it off or we did after repeated failed deliveries: re-enable it once your receiver is answering.

Sending

Why am I out of sending allowance?

A send refused with 429 outbound_limit_reached says why in reason. For temporary_exhaustion, retry at sufficient_capacity_at. For message_exceeds_allowance, the message needs more than the whole allowance, so waiting won't help: send it to fewer recipients or ask for more.

Every To, Cc and Bcc recipient counts once against the account's rolling 24-hour allowance, shared by all its inboxes; deleting sent mail doesn't give any back. Check usage on the Account home, with GET /v1/outbound/quota, or with get_outbound_quota from a connected agent.

Why is a recipient not allowed?

403 recipient_not_allowed means the inbox's sending rules don't permit one or more recipients, which the error names. Check every To, Cc and Bcc address, including ones a reply-all filled in. Nothing was sent or charged. Domain rules match the exact domain, not its subdomains. Only the account owner can change the rules, in Account → Sending rules.

Did my message actually send?

Check message.status in the response, not just HTTP success or a successful tool call. accepted means the provider accepted it, not that it reached the recipient's inbox. rejected means it was refused; error_code says why. unknown means we couldn't confirm either way: don't send a replacement, recover it instead. See Inspect the outcome.

What should I do after a timeout or lost send response?

Repeat the same send, reply or forward with its original idempotency key and payload within 24 hours: you get the original attempt back instead of a second email. For a draft, send the same draft ID again; that protection doesn't expire. Without a key, or after 24 hours, check sent mail before sending again. See safe retries and draft submission.

Finding mail

Why is a listing empty or missing messages?

Confirm the inbox ID, and that you're in the right listing: received mail, sent mail and drafts are listed separately. Filters combine, so a message must match every one you supply, and label names are case-sensitive; try again without filters. To read past the first page, follow next_cursor with the same filters and order; start again from the first page to see new arrivals or after changing the query. See Find mail and pagination. If an email never arrived at all, see expected email.

Why does search miss text I can see in an attachment?

Search covers subjects and message text, not attachment contents or filenames. It matches words and quoted phrases, not meanings or arbitrary substrings. To search a file, download the original attachment and use your own tools. See search matching.

Does reading a message mark it read?

No. Fetching mail changes nothing. For a shared read/unread convention, add or remove a read label (Track read, unread and starred mail); unlabeled mail counts as unread. Track finished work with your own list of handled message IDs or work labels.

Still stuck? Contact support with what you tried, roughly when, and the error code and X-Request-ID if you have them.

On this page