# Track read, unread and starred mail

Mark mail read or starred and find what's unread, in step with the Account.

Source: https://cherami.to/docs/guides/read-unread



Mail is read or starred when it carries the `read` or `starred` label. The Account uses the same labels, so marks made through the API, MCP or [Account → Inboxes](https://cherami.to/account/inboxes) show in all three. A received message without `read` is unread. Opening a message, in any of them, doesn't mark it read: add the label.

## Find unread messages [#find-unread-messages]

Set `CHERAMI_API_KEY` and `INBOX_ID`, then list received mail without `read`:

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

With MCP, call `list_messages`:

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

Results are newest first. Follow `next_cursor` with the same filter for more; start each check without one. For an unread count, use the same filter on `GET /v1/inboxes/INBOX_ID/messages/count` or `count_messages`.

## Mark a message read [#mark-a-message-read]

Once you've [read the message](https://cherami.to/docs/guides/receiving#read-a-message), add the label:

```bash
curl --request PATCH "https://cherami.to/v1/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $CHERAMI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"add_labels":["read"]}'
```

With MCP, call `update_message_labels`:

```json
{"message_id":"MESSAGE_ID","add_labels":["read"]}
```

Other labels are kept. To mark it unread, send `remove_labels` instead.

## Star mail [#star-mail]

Star and unstar the same way with `starred`; for sent mail, use `PATCH /v1/sent/MESSAGE_ID` or `update_sent_message_labels`. Find starred mail with `labels_all=starred` on the received, sent or conversation listing. Labels sit on single messages, not whole conversations; to star a conversation, use `update_thread_labels` as in [Label a conversation](https://cherami.to/docs/guides/labels#label-a-conversation).

[Organize mail with labels](https://cherami.to/docs/guides/labels) · [Labels reference](https://cherami.to/docs/api/labels)
