API reference
Labels API
Named colours on messages. Every labels endpoint with its scope, parameters, body and an example answer.
Base URL https://api.dissolve.email. Send an API key or OAuth access token as Authorization: Bearer <token> (Authentication); an OAuth token needs the scope on each endpoint. Errors follow one shape.
| Endpoint | Summary |
|---|---|
PUT /v1/messages/{messageId}/labels/{labelId} | Label a message |
DELETE /v1/messages/{messageId}/labels/{labelId} | Take a label off a message |
GET /v1/labels | List labels |
POST /v1/labels | Create a label |
PATCH /v1/labels/{id} | Change a label |
DELETE /v1/labels/{id} | Delete a label |
Label a message
/v1/messages/{messageId}/labels/{labelId}messages:writePro and upPuts one of your labels on a message in an inbox you own or that a team shares with you. Doing it twice is harmless.
Path parameters
| Name | Description |
|---|---|
messageId | The message id. |
labelId | The label id. |
curl -X PUT "https://api.dissolve.email/v1/messages/$MESSAGE_ID/labels/$LABEL_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.addLabel(messageId, labelId);import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.put(f"https://api.dissolve.email/v1/messages/{message_id}/labels/{label_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"success": true
}Take a label off a message
/v1/messages/{messageId}/labels/{labelId}messages:writePro and upRemoves one of your labels from a message.
Path parameters
| Name | Description |
|---|---|
messageId | The message id. |
labelId | The label id. |
curl -X DELETE "https://api.dissolve.email/v1/messages/$MESSAGE_ID/labels/$LABEL_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.removeLabel(messageId, labelId);import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/messages/{message_id}/labels/{label_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"success": true
}List labels
/v1/labelsmessages:readPro and upYour labels, by name, with how many your plan allows (Pro 10, Business 50).
curl "https://api.dissolve.email/v1/labels" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listLabels();import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get("https://api.dissolve.email/v1/labels", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"labels": [
{
"id": "lbl5Tq8WmZ1rXc3Vn7KpA",
"name": "Receipts",
"color": "#8b5cf6",
"createdAt": "2026-11-19T10:00:00.000Z"
}
],
"limit": 10,
"used": 1
}Create a label
/v1/labelsrules:managePro and upA named colour to put on messages, by hand or by a rule.
Body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | Unique on the account. At most 50 characters. |
color | string | no | A hex colour such as #8b5cf6. Default #8b5cf6. |
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(); // reads DISSOLVE_API_KEY
const result = await client.v1.createLabel({
name: "Receipts",
color: "#8b5cf6"
});import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post("https://api.dissolve.email/v1/labels", json={
"name": "Receipts",
"color": "#8b5cf6"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 201
{
"id": "lbl5Tq8WmZ1rXc3Vn7KpA",
"name": "Receipts",
"color": "#8b5cf6",
"createdAt": "2026-11-19T10:00:00.000Z"
}Change a label
/v1/labels/{id}rules:managePro and upRenames or recolours a label.
Path parameters
| Name | Description |
|---|---|
id | The label id. |
Body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
name | string | no | A new name. At most 50 characters. |
color | string | no | A new hex colour. |
curl -X PATCH "https://api.dissolve.email/v1/labels/$LABEL_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Invoices"}'import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.updateLabel(labelId, {
name: "Invoices"
});import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.patch(f"https://api.dissolve.email/v1/labels/{label_id}", json={
"name": "Invoices"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"success": true
}Delete a label
/v1/labels/{id}rules:managePro and upDeletes the label and takes it off every message.
Path parameters
| Name | Description |
|---|---|
id | The label id. |
curl -X DELETE "https://api.dissolve.email/v1/labels/$LABEL_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteLabel(labelId);import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/labels/{label_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"success": true
}Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown