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
| Field | What it does |
|---|---|
name | Required, at most 50 characters, unique on your account |
color | A 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"}'import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve();
const label = await client.v1.createLabel({ name: 'Receipts', color: '#8b5cf6' });import os, requests
HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
label = requests.post(
"https://api.dissolve.email/v1/labels",
json={"name": "Receipts", "color": "#8b5cf6"},
headers=HEADERS,
).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
{ "labels": [{ "id": "lbl5Tq8WmZ1rXc3Vn7KpA", "name": "Receipts", "color": "#8b5cf6", "createdAt": "2026-11-19T10:00:00.000Z" }], "limit": 10, "used": 1 }/v1/labels/{id}rules:managePro and up
Send a new name, a new color, or both.
/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"await client.v1.addLabel(messageId, labelId);requests.put(f"https://api.dissolve.email/v1/messages/{message_id}/labels/{label_id}", headers=HEADERS)/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):
/api/labels/messages/{messageId}API key or session{ "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.
{ "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"labelled = requests.get(
f"https://api.dissolve.email/v1/inboxes/{inbox_id}/messages",
params={"label": label_id},
headers=HEADERS,
).json()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