cherami.
Guides

Track read, unread and starred mail

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

Read as Markdown ↗

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 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

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

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:

{"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

Once you've read the message, add the label:

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:

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

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

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.

Organize mail with labels · Labels reference

On this page