Skip to content
docs
Browse the docsLabels

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.

EndpointSummary
PUT /v1/messages/{messageId}/labels/{labelId}Label a message
DELETE /v1/messages/{messageId}/labels/{labelId}Take a label off a message
GET /v1/labelsList labels
POST /v1/labelsCreate a label
PATCH /v1/labels/{id}Change a label
DELETE /v1/labels/{id}Delete a label

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.

Path parameters

NameDescription
messageIdThe message id.
labelIdThe label id.
curl -X PUT "https://api.dissolve.email/v1/messages/$MESSAGE_ID/labels/$LABEL_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "success": true
}

Take a label off a message

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

Removes one of your labels from a message.

Path parameters

NameDescription
messageIdThe message id.
labelIdThe label id.
curl -X DELETE "https://api.dissolve.email/v1/messages/$MESSAGE_ID/labels/$LABEL_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "success": true
}

List labels

GET/v1/labelsmessages:readPro and up

Your 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"

Response 200

JSON
{
  "labels": [
    {
      "id": "lbl5Tq8WmZ1rXc3Vn7KpA",
      "name": "Receipts",
      "color": "#8b5cf6",
      "createdAt": "2026-11-19T10:00:00.000Z"
    }
  ],
  "limit": 10,
  "used": 1
}

Create a label

POST/v1/labelsrules:managePro and up

A named colour to put on messages, by hand or by a rule.

Body (application/json)

NameTypeRequiredDescription
namestringyesUnique on the account. At most 50 characters.
colorstringnoA 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"}'

Response 201

JSON
{
  "id": "lbl5Tq8WmZ1rXc3Vn7KpA",
  "name": "Receipts",
  "color": "#8b5cf6",
  "createdAt": "2026-11-19T10:00:00.000Z"
}

Change a label

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

Renames or recolours a label.

Path parameters

NameDescription
idThe label id.

Body (application/json)

NameTypeRequiredDescription
namestringnoA new name. At most 50 characters.
colorstringnoA 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"}'

Response 200

JSON
{
  "success": true
}

Delete a label

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

Deletes the label and takes it off every message.

Path parameters

NameDescription
idThe label id.
curl -X DELETE "https://api.dissolve.email/v1/labels/$LABEL_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "success": true
}

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