Troubleshooting and FAQ
Resolve access problems, missing mail, blocked sends and unexpected search results.
Read as Markdown ↗Find the symptom below, then follow the linked guide for the full procedure. For client setup or missing tools, start with MCP troubleshooting.
Access
What if my API key is lost or revoked?
Follow Recover account access to approve a new key for the same account and update your application's private configuration. Your inboxes and mail remain in place. If the old key was exposed, revoke it in Account → API keys; issuing a replacement does not disable it.
Should I use Claim or reconnect with OAuth?
Use your application's connection flow for an OAuth MCP connection. Claim issues an API key for the HTTP API, SDKs or an MCP client explicitly configured to use a key. The six-word Claim phrase is exchanged for a permanent key; it is not itself a bearer credential.
A client reporting “Connected” may have reached public tool discovery without establishing access to your mail. Try listing inboxes. If that fails, follow the MCP connection diagnostics for your authentication method rather than switching methods blindly.
Receiving
Why has an expected email not appeared?
Check the exact address returned for the inbox and list its received messages without text, sender or recipient filters. Those filters can hide mail whose content is not ready. Follow later pages if needed; a count alone does not tell you which messages arrived.
Inspect the inbox's receiving rules. A matching visible From address or domain is rejected before storage, so there is no quarantined copy to recover. Saved rules are not a rejection log and cannot prove why a particular message is missing. Ask the sender to check the destination and any delivery error. If the message appears but has no body, check its processing state below.
Why can I see a message but not read its content?
Check processing_status: only ready supplies prepared content. Retain unfinished message IDs for a later check rather than marking them handled. For failed processing or a 503 response, follow content readiness and raw MIME recovery.
Does Cherami provide webhooks?
Cherami does not currently provide customer webhooks. Your application or running agent must poll for mail. Incoming mail does not start an agent, and checks stop when the process exits.
Follow Receive and poll for mail to bound each run, paginate and handle unfinished content. The automation cookbooks provide runnable examples.
Sending
Why am I out of sending allowance?
Check current usage in Account or through get_outbound_quota. All inboxes share the allowance; deleting sent mail does not refund it.
For a temporary block, use sufficient_capacity_at and Retry-After when supplied, not just the first returning unit. If the message exceeds the full allowance, waiting will not help. Follow allowance recovery or request more capacity. Receiving and reading remain available.
Why is a recipient not allowed?
recipient_not_allowed means the inbox's sending rules do not permit every destination. Inspect the policy and check all To/Cc/Bcc addresses, including recipients derived by reply-all. Cherami rejects the new attempt as a whole without submission or allowance use.
Only the human can change Sending rules. Ask them to review the intended recipients; do not switch inboxes or change addresses to bypass the restriction. Domain rules match exact domains, not their subdomains. See Restrict sending destinations.
Did my message actually send?
Inspect the returned message's status, not just HTTP success or a successful tool call. accepted means the provider accepted submission, not confirmed inbox delivery. rejected means submission was explicitly rejected; inspect the error before considering a new attempt. unknown means acceptance could not be established, so automatically sending again risks a duplicate.
If outcome_persisted is false, keep the immediate receipt: later reads may lag its known outcome. See Inspect the outcome.
What should I do after a timeout or lost send response?
For an ordinary send, reply or forward, recover with the original idempotency key and exact payload within the original 24-hour window. Do not generate another key to resolve uncertainty. Without that protection, or after it expires, inspect sent mail rather than repeating the send. A recovered unknown result does not restart submission.
For a saved draft, recover using the same draft ID: its submission protection does not expire with an optional retry key. Do not create a replacement draft just to retry. Follow send recovery or draft submission guidance.
Finding mail
Why is a listing empty or missing messages?
List inboxes and confirm the selected inbox ID. Received mail, sent attempts and drafts have separate listings. Then remove filters and start a fresh listing. Conditions combine, so a message must satisfy every supplied condition; label names are case-sensitive.
Follow next_cursor with unchanged filters and order to read later pages. Restart from the first page when changing the query or checking for new arrivals. Listings are live views, not snapshots. See Find mail and the pagination and error reference.
Why does search miss text I can see in an attachment?
Search covers prepared subjects and message bodies, not attachment contents or filenames. It matches words and quoted phrases, not meanings or arbitrary substrings. Download the original attachment and use your own tools to read or search it. Cherami does not extract document text for you.
See search matching for the full query behavior.
Does reading a message mark it read?
No. Fetching mail does not change labels or create read state. For a shared read/unread convention, explicitly add or remove a read label using Track read and unread mail. Unlabeled mail counts as unread under that convention, even if someone fetched it before.
Track completed work separately using private handled IDs or work labels.
For a problem these checks do not resolve, contact support with the operation, approximate time, error code and request ID if available. Leave out credentials, approval phrases and unrelated private mail.