# Organize mail with labels

Tag correspondence and find messages belonging to a task or category.

Source: https://cherami.to/docs/guides/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 message [#tag-a-message]

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:

```http
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:

```json
{"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 mail [#find-tagged-mail]

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:

```json
{"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](https://cherami.to/docs/guides/receiving).

## Organize a batch [#organize-a-batch]

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 copy [#tag-an-outgoing-copy]

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](https://cherami.to/docs/api/labels) · [Sending and retry guidance](https://cherami.to/docs/guides/sending)