# Organize mail with labels

Label mail and find the messages that belong to a task or category.

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

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

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

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

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:

```json
{"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 batch [#organize-a-batch]

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 conversation [#label-a-conversation]

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

```bash
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](https://cherami.to/docs/api/threads/update-thread-labels).

## Label mail as you send it [#label-mail-as-you-send-it]

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](https://cherami.to/docs/guides/read-unread).

[Label fields and limits](https://cherami.to/docs/api/labels)