# Rules and templates

> Forward, label or drop new mail by sender or subject with inbox rules, and save inbox settings as templates to make new inboxes from.

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

## Inbox rules

A rule looks at every new message in your inboxes as it arrives and does one thing with it: forward it, label it or drop it. Rules are on Pro (10 rules) and Business (50 rules).

How a message is matched:

- Each rule has a sender pattern, a subject pattern, or both. A rule matches when **either** of its patterns matches.
- Patterns are globs: `*` is any run of characters, `?` is one character, and case is ignored. A pattern matches the whole value, so `*@github.com` matches `noreply@github.com` and `github` alone matches only the exact text `github`.
- Rules are tried from the highest `priority` down (0 to 100). The **first** rule that matches is the only one applied.
- Disabled rules are skipped.

| `action` | `action_value` | What happens |
|---|---|---|
| `label` | A label name | The message is stored with that [label](/labels). A label of that name is made if you have none. |
| `forward` | An email address | The message is stored and a copy is sent to the address (needs a plan with forwarding; not to dissolve.email or disposable addresses). For that message it takes the place of the inbox's own forwarding. |
| `delete` | Nothing | The message is dropped as it arrives: it is never stored and sends no `message.received` webhook. |

> [!WARNING] Delete means never seen
> A `delete` rule drops mail before it is stored. Test its pattern with a `label` rule first.

Patterns are at most 200 characters with at most 10 `*` each.

### Create a rule

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

| Field | What it does |
|---|---|
| `name` | Required. What the rule is for, at most 100 characters. |
| `from_pattern` | Glob for the sender address, or null. |
| `subject_pattern` | Glob for the subject, or null. At least one pattern is required. |
| `action` | Required. `forward`, `delete` or `label`. |
| `action_value` | The forward address or the label name. |
| `enabled` | Default `true`. |
| `priority` | 0 to 100, default 0. Higher runs first. |

```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();
const rule = await client.v1.createRule({
  name: 'Label receipts',
  subject_pattern: '*receipt*',
  action: 'label',
  action_value: 'Receipts',
});
```

```python Python
import os, requests

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

```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"
}
```

Requests use `snake_case` field names; answers use `camelCase`. Going over your plan's count answers `400 rule_limit`; a bad pattern `400 invalid_pattern`; a forward rule without forwarding on your plan `403 upgrade_required`.

### List, change and delete rules

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

```json
{ "rules": [{ "id": "rul3Kd7PxN2qVw9Zc4TmB", "name": "Label receipts", "subjectPattern": "*receipt*", "action": "label", "actionValue": "Receipts", "enabled": true, "priority": 0 }], "limit": 10, "used": 1 }
```

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

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

Send only the fields that change. The rule is checked again as a whole, so you cannot remove its last pattern.

```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
await client.v1.updateRule(ruleId, { enabled: false });
```

```python Python
requests.patch(f"https://api.dissolve.email/v1/rules/{rule_id}", json={"enabled": False}, headers=HEADERS)
```

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

Two more calls take an API key or the signed-in app, outside `/v1`: flip a rule on or off, and set the priority of many rules at once with `{"rules": [{"id": "...", "priority": 10}]}`.

`POST /api/inbox-rules/{id}/toggle` (API key or signed-in session)

`POST /api/inbox-rules/reorder` (API key or signed-in session)

## Templates

A template saves settings to make inboxes from: a domain, an address to forward to and a webhook address kept with it. Pass its id as `templateId` when you [create an inbox](/inboxes#create-an-inbox) and its domain and forwarding are applied. Free accounts may save 3 templates, Pro 10 and Business 25. Forwarding in a template needs Pro or Business.

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

| Field | What it does |
|---|---|
| `name` | Required, at most 100 characters. |
| `domain` | A domain from `GET /v1/domains`, or null. |
| `forward_to` | An address to forward new inboxes' mail to, or null. |
| `webhook_url` | A webhook address kept with the template, or null. |
| `is_default` | Default `false`. |

```bash cURL
curl -X POST https://api.dissolve.email/v1/templates \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Forwarded", "forward_to": "me@example.com", "is_default": true}'
```

```ts TypeScript
const template = await client.v1.createTemplate({ name: 'Forwarded', forward_to: 'me@example.com', is_default: true });
const inbox = await client.v1.createInbox({ templateId: template.id });
```

```python Python
template = requests.post(
    "https://api.dissolve.email/v1/templates",
    json={"name": "Forwarded", "forward_to": "me@example.com", "is_default": True},
    headers=HEADERS,
).json()
```

```json
{ "id": "tpl9Wm2QxK5rNc8Vz1LpT", "name": "Forwarded", "domain": null, "forwardTo": "me@example.com", "webhookUrl": null, "isDefault": true, "createdAt": "2026-11-19T10:00:00.000Z", "updatedAt": "2026-11-19T10:00:00.000Z" }
```

`GET /v1/templates` (scope `inboxes:read`)

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

Deleting a template leaves inboxes made from it as they are. Changing a template, and making one the default, take an API key or the signed-in app:

`PATCH /api/inbox-templates/{id}` (API key or signed-in session)

`POST /api/inbox-templates/{id}/set-default` (API key or signed-in session)

> [!NOTE] Scopes
> Rules, labels and templates are managed with `rules:manage`; listing templates needs only `inboxes:read`.
