Skip to main content
A label has two halves that live in different places, and knowing which is which explains everything else on this page. The keyword is an IMAP flag on the message itself. It is what makes a label real: apply one here and it is visible in Thunderbird, on a phone, anywhere the mailbox is opened. The name and colour are a row in Ruber’s database — the catalogue that says what that keyword is called. Required permission: Labels → Read for listing, Labels → Write to create, rename or delete. Putting a label on a message is messages:write, because that changes the message, not the catalogue.
These are organization labels, not personal ones.Labels in the Ruber web app belong to a person: two people in one organization keep different catalogues and neither sees the other’s. An API key has no person, so it gets its own kind — a label owned by the organization and readable by every member.A key therefore cannot see, rename, delete or apply anybody’s personal labels. A key leaked from a CI job should not reveal how a colleague files their mail. Organization labels created here do show up for your team in the web app, which is the point: an integration’s label has to be nameable in the interface where someone reads the message.

​
List labels

Takes no parameters — labels belong to the organization, not to a mailbox. keyword is what you pass to add_labels / remove_labels. id is what you pass to the two endpoints below.

​
Create a label

201 Created, returning the label including its keyword.
You do not choose the keyword. It is derived from the name by the database, so every caller produces the same one, and it is checked against every keyword already used in the organization — including members’ personal labels. A label named Invoices in an organization where somebody already uses that keyword becomes Invoices-2.That collision check matters: a keyword is an IMAP flag, so two labels sharing one are the same label as far as the mailbox is concerned. An integration tagging “Invoices” would otherwise silently light up a colleague’s personal filter.

​
Rename or recolour

Send at least one of name or colour.
A rename does not change the keyword, and that is deliberate.The keyword is a flag sitting on every message already tagged. Changing it would mean rewriting flags across the whole mailbox to keep those messages labelled — slow, not atomic, and visible to every other client mid-flight.So renaming is a one-row update, tagged messages stay tagged, and the keyword you stored stays valid. Do not derive the keyword from the name in your own code; read it from the API.

​
Delete a label

Deleting a label leaves the keyword on the messages. The name and colour go; the flag stays.Stripping the flag from every tagged message would be a mailbox-wide rewrite triggered by one DELETE, and destructive in a way nobody asked for — a keyword set by somebody’s desktop client belongs to them, not to our row about it.The practical consequence is good: recreate a label with the same name and it recovers the same keyword, so the messages light up again. An accidental delete is survivable.

​
Putting a label on a message

That is a message change, so it lives on the message endpoint and needs messages:write:
Both take keywords, not names, and every keyword must be one of your organization’s labels — an unknown one is refused rather than written. Without that check add_labels would write arbitrary atoms onto a message as IMAP flags, which the mailbox would then carry forever with nothing able to name them. See Update a message for the full endpoint.

​
Errors

See Errors for the full response shape.