Receive and poll for mail

Mail sent to your inbox waits there until you check: it doesn't wake your agent. List new messages, then fetch the ones you want to read. To be told when mail arrives instead, use a webhook.

Find messages you have not handledCopy Anchor Link

Set INBOX_ID and CHERAMI_API_KEY, then list received mail that doesn't carry a handled label:

curl --get "https://cherami.to/v1/inboxes/$INBOX_ID/messages" \
  -H "Authorization: Bearer $CHERAMI_API_KEY" \
  --data-urlencode 'labels_none=handled' \
  --data-urlencode 'limit=20'

With MCP, call list_messages with the same arguments:

{"inbox_id":"INBOX_ID","labels_none":["handled"],"limit":20}

Results are newest first; follow next_cursor for more pages.

handled is a label you choose: nothing sets it for you, and fetching a message doesn't change it. Add it once you've dealt with a message and the message drops out of this list. To show in the Account which mail has been read, add read as well (read and unread).

Ready HTTP results carry a preview excerpt of the message text (truncated says if it was cut), enough to choose what to open. MCP's list_messages returns sender and subject; include_content: true adds each body, up to 2,000 characters.

Read a messageCopy Anchor Link

Fetch GET /v1/messages/MESSAGE_ID or call get_message:

curl --fail-with-body --silent --show-error \
  "https://cherami.to/v1/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $CHERAMI_API_KEY"

Once processing_status is ready, content.reply_text holds just the new reply without quoted history, and content.text and content.html hold the full message; read those when the sender answered inline or forwarded something. reply_text is null when no reply could be extracted; an empty string is a real result, so don't fall back to the quote. With MCP, get_message returns the new reply as body when it can be extracted, otherwise the full text; pass format: "full" for the original bodies.

content.from is whatever the sender wrote, and we don't verify it. envelope_from is the SMTP sender, often a bounce address. Files are listed in content.attachments; download them by ID.

Wait for content, not just receiptCopy Anchor Link

A message that has just arrived may still be pending or processing, with no content yet; fetch it again shortly. If it's failed, download the original email and read it with your own MIME tools.

Check on a scheduleCopy Anchor Link

Agree on when to check and when to stop, such as every ten minutes until the task ends. Start each check from the first page, without a cursor, and give it a page budget. If the budget runs out before you reach mail you've already seen, report that more is waiting rather than an empty inbox. If nothing keeps running between checks, say that checking has stopped instead of promising to keep watching.

Related guidesCopy Anchor Link

To find particular mail, search and filter the listings. To stop mail from a sender, add them to the inbox's receiving rules in Account.

For complete automated runs, see Collect and clarify project updates and Answer project questions.

Received-message fields and downloads · Pagination and errors