Organize mail with labels

Use labels to organize individual messages without moving or deleting them. A message can have several tags, such as a project name and needs-review. Guests can label mail without verifying an email address.

Tag a messageCopy Anchor Link

With connected tools, use update_message_labels for received mail or update_sent_message_labels for outgoing copies. Supply the message ID and the labels to add or remove. These tools change the specified tags rather than replacing everything already on the message.

With HTTP, send an authenticated request to the corresponding message endpoint:

PATCH /v1/messages/MESSAGE_ID HTTP/1.1
Host: cherami.to
Authorization: Bearer YOUR_CREDENTIAL
Content-Type: application/json

{"add_labels":["needs-review"]}

After handling the message, you can change its tags in one request:

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

Use list_labels with your inbox ID to discover existing names and their received/sent message counts. With HTTP, use GET /v1/inboxes/INBOX_ID/labels. An optional prefix narrows the vocabulary. Choose consistent names with the other agents using the account: names are case-sensitive, and labels are shared with everyone who has account access.

Find tagged mailCopy Anchor Link

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

For a more specific view, combine labels_all, labels_any, and labels_none. For example, pass this filter to list_messages alongside 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, excluding completed work. To find mail you have not handled, use labels_none: ["handled"]. That includes newly arrived mail with no labels. After successful processing, explicitly add handled; reading alone changes nothing.

With HTTP, repeat each group parameter for its names, such as ?labels_all=project-x&labels_any=needs-reply&labels_any=waiting&labels_none=done. Keep the same filters when following a cursor. To change conditions, start again without a cursor.

Labels describe work; they do not perform it. A needs-review tag does not notify anyone, and handled does not prevent another agent from processing the message. Reading mail does not automatically add or remove tags. For finding new arrivals, keep following the polling guidance.

Organize a batchCopy Anchor Link

Select the messages first, then use bulk_update_message_labels or bulk_update_sent_message_labels with up to 100 explicit message_ids and shared additions/removals. HTTP uses PATCH /v1/messages/labels or PATCH /v1/sent/labels. Every target must be accessible or the entire batch is rejected without changes.

To rename a category, list received and sent copies with its old name, then add the new name and remove the old one in batches. Finish both copy types and check the old filter again. There is no global rename transaction: coordinate with agents still applying the old name.

Tag an outgoing copyCopy Anchor Link

Include labels in send_message or the HTTP send request to organize the saved outgoing copy immediately. Tags are private to your Cherami account and are not included in the delivered email. A reply gets only the labels explicitly supplied for that reply.

Label fields and limits · Sending and retry guidance