Skip to content
docs
Browse the docsLabels

Mail

Labels

Name and colour your mail. Create labels, put them on messages by hand or with a rule, and list only the messages that carry one.

A label is a name and a colour you put on messages, such as Receipts or Needs review. Labels belong to your account, not to one inbox, and each person's labels are their own: a teammate does not see yours on a shared inbox. Labels are on Pro (10 labels) and Business (50).

Create a label

POST/v1/labelsrules:managePro and up
FieldWhat it does
nameRequired, at most 50 characters, unique on your account
colorA hex colour such as #8b5cf6 (the default)
curl -X POST https://api.dissolve.email/v1/labels \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Receipts", "color": "#8b5cf6"}'
JSON
{ "id": "lbl5Tq8WmZ1rXc3Vn7KpA", "name": "Receipts", "color": "#8b5cf6", "createdAt": "2026-11-19T10:00:00.000Z" }

A name you already use answers 409 conflict; one label past your plan's count answers 400 label_limit.

List, rename and delete

GET/v1/labelsmessages:readPro and up
JSON
{ "labels": [{ "id": "lbl5Tq8WmZ1rXc3Vn7KpA", "name": "Receipts", "color": "#8b5cf6", "createdAt": "2026-11-19T10:00:00.000Z" }], "limit": 10, "used": 1 }
PATCH/v1/labels/{id}rules:managePro and up

Send a new name, a new color, or both.

DELETE/v1/labels/{id}rules:managePro and up

Deleting a label takes it off every message.

Label a message

PUT/v1/messages/{messageId}/labels/{labelId}messages:writePro and up

Puts one of your labels on a message in an inbox you own or that a team shares with you. Doing it twice is harmless.

curl -X PUT https://api.dissolve.email/v1/messages/$MESSAGE_ID/labels/$LABEL_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
DELETE/v1/messages/{messageId}/labels/{labelId}messages:writePro and up

Takes the label off again. A label or message that is not yours, or a message whose inbox has expired, answers 404.

To see the labels on one message, ask with an API key or from the signed-in app (it is not part of /v1):

GET/api/labels/messages/{messageId}API key or session
JSON
{ "labels": [{ "id": "lbl5Tq8WmZ1rXc3Vn7KpA", "name": "Receipts", "color": "#8b5cf6", "appliedAt": "2026-11-19T10:02:11.000Z", "appliedByRuleId": null }] }

Label mail as it arrives

A rule with action: "label" labels every matching message as it is stored. Its action_value is the label's name, and the label is made if you have none by that name.

JSON
{ "name": "Label receipts", "subject_pattern": "*receipt*", "action": "label", "action_value": "Receipts" }

Only the labelled messages

Pass a label id as label when you list messages:

curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages?label=$LABEL_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

The filter looks at the inbox's newest 1,000 messages.

Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown