# Rules API

> Forward, label or delete new mail by sender or subject. Every rules endpoint with its scope, parameters, body and an example answer.

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

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 |
|---|---|
| `GET /v1/rules` | [List rules](#list-rules) |
| `POST /v1/rules` | [Create a rule](#create-a-rule) |
| `GET /v1/rules/{id}` | [Get a rule](#get-a-rule) |
| `PATCH /v1/rules/{id}` | [Change a rule](#change-a-rule) |
| `DELETE /v1/rules/{id}` | [Delete a rule](#delete-a-rule) |

### List rules

`GET /v1/rules` (scope `rules:manage`)

Your inbox rules, highest priority first, with how many your plan allows (Pro 10, Business 50).

```bash cURL
curl "https://api.dissolve.email/v1/rules" \
  -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.listRules();
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get("https://api.dissolve.email/v1/rules", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "rules": [
    {
      "id": "rul3Kd7PxN2qVw9Zc4TmB",
      "name": "Label receipts",
      "fromPattern": null,
      "subjectPattern": "*receipt*",
      "action": "label",
      "actionValue": "Receipts",
      "enabled": true,
      "priority": 0,
      "createdAt": "2026-11-19T10:00:00.000Z",
      "updatedAt": "2026-11-19T10:00:00.000Z"
    }
  ],
  "limit": 10,
  "used": 1
}
```

### Create a rule

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

A rule runs on every new message in your inboxes: when the sender or subject matches its glob pattern (`*` any run of characters, `?` one character, case ignored), it forwards, labels or deletes the message. At least one pattern is needed.

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | What the rule is for. At most 100 characters. |
| `from_pattern` | string or null | no | Glob matched against the sender address, such as *@github.com. At most 200 characters. |
| `subject_pattern` | string or null | no | Glob matched against the subject, such as *receipt*. At most 200 characters. |
| `action` | string | yes | What to do with a match. One of `forward`, `delete`, `label`. |
| `action_value` | string or null | no | The address to forward to, or the label name to apply. At most 255 characters. |
| `enabled` | boolean | no | Whether it runs. Default `true`. |
| `priority` | integer | no | Higher runs first. Default `0`. 0 to 100. |

```bash cURL
curl -X POST "https://api.dissolve.email/v1/rules" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Label receipts","subject_pattern":"*receipt*","action":"label","action_value":"Receipts"}'
```

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.createRule({
  name: "Label receipts",
  subject_pattern: "*receipt*",
  action: "label",
  action_value: "Receipts"
});
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post("https://api.dissolve.email/v1/rules", json={
  "name": "Label receipts",
  "subject_pattern": "*receipt*",
  "action": "label",
  "action_value": "Receipts"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `201`

```json
{
  "id": "rul3Kd7PxN2qVw9Zc4TmB",
  "name": "Label receipts",
  "fromPattern": null,
  "subjectPattern": "*receipt*",
  "action": "label",
  "actionValue": "Receipts",
  "enabled": true,
  "priority": 0,
  "createdAt": "2026-11-19T10:00:00.000Z",
  "updatedAt": "2026-11-19T10:00:00.000Z"
}
```

### Get a rule

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

One rule.

**Path parameters**

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

```bash cURL
curl "https://api.dissolve.email/v1/rules/$RULE_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.getRule(ruleId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/rules/{rule_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "id": "rul3Kd7PxN2qVw9Zc4TmB",
  "name": "Label receipts",
  "fromPattern": null,
  "subjectPattern": "*receipt*",
  "action": "label",
  "actionValue": "Receipts",
  "enabled": true,
  "priority": 0,
  "createdAt": "2026-11-19T10:00:00.000Z",
  "updatedAt": "2026-11-19T10:00:00.000Z"
}
```

### Change a rule

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

Changes any field; the rule is checked again as a whole.

**Path parameters**

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

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | no | What the rule is for. At most 100 characters. |
| `from_pattern` | string or null | no | Sender glob, or null. |
| `subject_pattern` | string or null | no | Subject glob, or null. |
| `action` | string | no | What to do with a match. One of `forward`, `delete`, `label`. |
| `action_value` | string or null | no | Forward address or label name. |
| `enabled` | boolean | no | Whether it runs. |
| `priority` | integer | no | Higher runs first. 0 to 100. |

```bash cURL
curl -X PATCH "https://api.dissolve.email/v1/rules/$RULE_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
```

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.updateRule(ruleId, {
  enabled: false
});
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.patch(f"https://api.dissolve.email/v1/rules/{rule_id}", json={
  "enabled": False
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

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

### Delete a rule

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

Deletes the rule.

**Path parameters**

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

```bash cURL
curl -X DELETE "https://api.dissolve.email/v1/rules/$RULE_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.deleteRule(ruleId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/rules/{rule_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

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