# Labels API

> Named colours on messages. Every labels endpoint with its scope, parameters, body and an example answer.

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

Base URL `https://api.dissolve.email`. Send an API key or OAuth access token as `Authorization: Bearer <token>` ([Authentication](/authentication)); an OAuth token needs the scope on each endpoint. Errors follow [one shape](/errors).

| Endpoint | Summary |
|---|---|
| `PUT /v1/messages/{messageId}/labels/{labelId}` | [Label a message](#label-a-message) |
| `DELETE /v1/messages/{messageId}/labels/{labelId}` | [Take a label off a message](#take-a-label-off-a-message) |
| `GET /v1/labels` | [List labels](#list-labels) |
| `POST /v1/labels` | [Create a label](#create-a-label) |
| `PATCH /v1/labels/{id}` | [Change a label](#change-a-label) |
| `DELETE /v1/labels/{id}` | [Delete a label](#delete-a-label) |

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

**Path parameters**

| Name | Description |
|---|---|
| `messageId` | The message id. |
| `labelId` | The label id. |

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.addLabel(messageId, labelId);
```

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

```json
{
  "success": true
}
```

### Take a label off a message

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

Removes one of your labels from a message.

**Path parameters**

| Name | Description |
|---|---|
| `messageId` | The message id. |
| `labelId` | The label id. |

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.removeLabel(messageId, labelId);
```

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

```json
{
  "success": true
}
```

### List labels

`GET /v1/labels` (scope `messages:read`)

Your labels, by name, with how many your plan allows (Pro 10, Business 50).

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listLabels();
```

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

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

### Create a label

`POST /v1/labels` (scope `rules:manage`)

A 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`. |

```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(); // reads DISSOLVE_API_KEY
const result = await client.v1.createLabel({
  name: "Receipts",
  color: "#8b5cf6"
});
```

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

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

### Change a label

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

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

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.updateLabel(labelId, {
  name: "Invoices"
});
```

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

```json
{
  "success": true
}
```

### Delete a label

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

Deletes the label and takes it off every message.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The label id. |

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteLabel(labelId);
```

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

```json
{
  "success": true
}
```
