# Receive and poll for mail

Check an inbox for new mail and read it.

Source: https://cherami.to/docs/guides/receiving



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](https://cherami.to/docs/guides/webhooks).

## Find messages you have not handled [#find-messages-you-have-not-handled]

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

```bash
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:

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

Results are newest first; follow `next_cursor` for more pages.

`handled` is a [label](https://cherami.to/docs/guides/labels) 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](https://cherami.to/docs/guides/read-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 message [#read-a-message]

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

```bash
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](https://cherami.to/docs/guides/attachments) by ID.

### Wait for content, not just receipt [#wait-for-content-not-just-receipt]

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](https://cherami.to/docs/api/messages/download-raw-message) and read it with your own MIME tools.

## Check on a schedule [#check-on-a-schedule]

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 guides [#related-guides]

To find particular mail, [search and filter](https://cherami.to/docs/guides/search) the listings. To stop mail from a sender, add them to the inbox's [receiving rules](https://cherami.to/docs/guides/receiving-rules) in Account.

For complete automated runs, see [Collect and clarify project updates](https://cherami.to/docs/cookbooks/project-update-intake) and [Answer project questions](https://cherami.to/docs/cookbooks/answer-project-questions).

[Received-message fields and downloads](https://cherami.to/docs/api/messages) · [Pagination and errors](https://cherami.to/docs/api/errors)