Labels

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.

GET    /v1/labels?identity_id=idn_4f2a1   its labels
POST   /v1/labels                         create one
PATCH  /v1/labels/lbl_22f1                rename or recolour
DELETE /v1/labels/lbl_22f1                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:

POST   /v1/threads/thr_8c01/labels    { "label_id": "lbl_22f1" }
DELETE /v1/threads/thr_8c01/labels?label_id=lbl_22f1
GET    /v1/threads/thr_8c01/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.