# Labels

Source: https://docs.simail.ai/api/labels/

> System and custom labels on messages and threads, how to filter by them, and which ones an agent may change.

Labels are short strings on messages. A thread's labels are the union of its messages' labels.

## System labels

| Label | Set by | Agents may change |
|---|---|---|
| `received` | simail, on inbound mail | no |
| `sent` | simail, on outbound mail | no |
| `unread` | simail, on inbound mail | yes |
| `important` | you | yes |
| `draft` | simail | no |
| `held` | simail; cleared when a human releases the message | no |
| `spam` | simail | no |
| `blocked` | simail (sender on a block list) | no |
| `trash` | `DELETE` on a message or thread | no (only by deleting) |

## Custom labels

Any other lowercase string up to 64 characters (`a-z`, `0-9`, `-`, `_`, `.`, `/`) is a custom label,
for example `orders` or `needs-human`. Agents may add and remove custom labels freely.

## Changing labels

`PATCH /v0/inboxes/{inbox_id}/messages/{message_id}`

`PATCH /v0/inboxes/{inbox_id}/threads/{thread_id}`

`POST /v0/inboxes/{inbox_id}/messages/batch-update`

All need `message_update` and take:

```json
{ "add_labels": ["orders"], "remove_labels": ["unread"] }
```

Trying to change a label agents may not change returns `400 validation_error`. Changes publish
`label.added` and `label.removed`. Sends can set labels on the sent copy with `labels`.

## Filtering

List and search endpoints take `labels=a,b` (all must match). `spam`, `blocked` and `trash` are left
out of listings unless you pass `include_spam`, `include_blocked` or `include_trash`, each of which
needs its `label_*_read` permission.

MCP: `list_labels` and `update_labels`.