Organize mail with labels

Labels organize individual messages without moving or deleting them. A message can have several, such as a project name and needs-review.

Label a messageCopy Anchor Link

With MCP, call update_message_labels for received mail or update_sent_message_labels for sent mail, with the message ID and the labels to add or remove. Labels you don't name stay as they are.

With HTTP, set MESSAGE_ID and CHERAMI_API_KEY:

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

For sent mail, use PATCH /v1/sent/MESSAGE_ID. Once you've dealt with a message, you can add and remove in one request:

{"add_labels":["handled"],"remove_labels":["needs-review"]}

list_labels (GET /v1/inboxes/INBOX_ID/labels) shows the labels already used in an inbox, with received and sent counts; an optional prefix narrows it. Names are case-sensitive and shared by everyone using the account. Labels don't lock a message, so when several agents work in one inbox, agree which one handles its mail.

Find labeled mailCopy Anchor Link

Pass labels_all: ["needs-review"] to list_messages, count_messages or list_sent. With HTTP, add ?labels_all=needs-review to the received listing, received count or sent listing.

Combine labels_all, labels_any and labels_none for a narrower view. For example, pass this to list_messages with your inbox ID:

{"labels_all":["project-x"],"labels_any":["needs-reply","waiting"],"labels_none":["done"]}

This finds project mail that needs a reply or is waiting, leaving out finished work. To find mail you haven't handled, use labels_none: ["handled"]; new mail has no labels, so it's included.

With HTTP, repeat each parameter for each name: ?labels_all=project-x&labels_any=needs-reply&labels_any=waiting&labels_none=done. Keep the same filters when following a cursor; to change them, start again without one.

Organize a batchCopy Anchor Link

Select the messages first, then call bulk_update_message_labels or bulk_update_sent_message_labels with up to 100 message_ids and the labels to add or remove. HTTP uses PATCH /v1/messages/labels or PATCH /v1/sent/labels. If any message isn't found, nothing changes.

There's no rename: add the new label and remove the old one, in batches, on both received and sent mail.

Label a conversationCopy Anchor Link

update_thread_labels takes a thread_id and the labels to add or remove. It updates every message now in the conversation, received and sent; later replies don't get the labels. With HTTP, set THREAD_ID:

curl --request PATCH "https://cherami.to/v1/threads/$THREAD_ID" \
  -H "Authorization: Bearer $CHERAMI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"add_labels":["handled"],"remove_labels":["needs-review"]}'

The response gives how many received and sent messages changed. Thread operation reference.

Label mail as you send itCopy Anchor Link

Add labels to send_message or the send request to label the message as you send it. Recipients never see labels. A reply gets only the labels you give it.

For read and starred mail that shows in the Account, see Track read, unread and starred mail.

Label fields and limits