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.