# Labels

> Label a Pidgeon conversation rather than a message, because a label is a fact about the whole thread and not about one mail inside it.

A folder is where a conversation *is*; a label is something it **is also**. A
conversation has one folder and any number of labels, which is the difference
that makes labels worth having — filing something in Invoices does not take
it out of the inbox.

Labels belong to an address, not to the workspace.

```text
GET    /v1/labels?identity_id=0c939bd7-2d69-4150-a2ac-de994f0e4887   its labels
POST   /v1/labels                         create one
PATCH  /v1/labels/23410ea6-0ad0-4d5c-a0ec-0db8c45e6502                rename or recolour
DELETE /v1/labels/23410ea6-0ad0-4d5c-a0ec-0db8c45e6502                remove it
```

Deleting a label removes the label, not the conversations it was on. There is
no version of this that destroys mail.

Putting one on a conversation, and taking it off:

```text
POST   /v1/threads/e0bc3cf8-4f01-4a04-a959-4e22b6df746f/labels    { "label_id": "23410ea6-0ad0-4d5c-a0ec-0db8c45e6502" }
DELETE /v1/threads/e0bc3cf8-4f01-4a04-a959-4e22b6df746f/labels?label_id=23410ea6-0ad0-4d5c-a0ec-0db8c45e6502
GET    /v1/threads/e0bc3cf8-4f01-4a04-a959-4e22b6df746f/labels
```

`POST` answers the conversation's **whole** label list rather than the one you
added, so a client never has to follow a write with a read to know where it
stands. `DELETE` takes the id in the query because the label hangs off the
conversation rather than being a thing underneath it.

**They are on the conversation, not the message.** A label applied to one
message labels the thread, and the other messages in it arrive in that
mailbox too. That is surprising exactly once, and the alternative —
message-level labels for IMAP's sake — would be two models of one feature.