# 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.

Source: https://docs.dissolve.email/labels

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/labels` (scope `rules:manage`)

| Field | What it does |
|---|---|
| `name` | Required, at most 50 characters, unique on your account |
| `color` | A hex colour such as `#8b5cf6` (the default) |

```bash cURL
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"}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve();
const label = await client.v1.createLabel({ name: 'Receipts', color: '#8b5cf6' });
```

```python Python
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()
```

```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/labels` (scope `messages:read`)

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

`PATCH /v1/labels/{id}` (scope `rules:manage`)

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

`DELETE /v1/labels/{id}` (scope `rules:manage`)

Deleting a label takes it off every message.

## Label a message

`PUT /v1/messages/{messageId}/labels/{labelId}` (scope `messages:write`)

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.

```bash cURL
curl -X PUT https://api.dissolve.email/v1/messages/$MESSAGE_ID/labels/$LABEL_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
await client.v1.addLabel(messageId, labelId);
```

```python Python
requests.put(f"https://api.dissolve.email/v1/messages/{message_id}/labels/{label_id}", headers=HEADERS)
```

`DELETE /v1/messages/{messageId}/labels/{labelId}` (scope `messages:write`)

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 signed-in 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](/rules) 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](/messages#list-messages):

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

```python Python
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.

> [!NOTE] Scopes
> Listing labels needs `messages:read`; labelling a message needs `messages:write`; making, changing and deleting labels needs `rules:manage`.
