Skip to content
docs
Browse the docsRules

API reference

Rules API

Forward, label or delete new mail by sender or subject. Every rules 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
GET /v1/rulesList rules
POST /v1/rulesCreate a rule
GET /v1/rules/{id}Get a rule
PATCH /v1/rules/{id}Change a rule
DELETE /v1/rules/{id}Delete a rule

List rules

GET/v1/rulesrules:managePro and up

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

curl "https://api.dissolve.email/v1/rules" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

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/rulesrules:managePro and up

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)

NameTypeRequiredDescription
namestringyesWhat the rule is for. At most 100 characters.
from_patternstring or nullnoGlob matched against the sender address, such as *@github.com. At most 200 characters.
subject_patternstring or nullnoGlob matched against the subject, such as receipt. At most 200 characters.
actionstringyesWhat to do with a match. One of forward, delete, label.
action_valuestring or nullnoThe address to forward to, or the label name to apply. At most 255 characters.
enabledbooleannoWhether it runs. Default true.
priorityintegernoHigher runs first. Default 0. 0 to 100.
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"}'

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}rules:managePro and up

One rule.

Path parameters

NameDescription
idThe rule id.
curl "https://api.dissolve.email/v1/rules/$RULE_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

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}rules:managePro and up

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

Path parameters

NameDescription
idThe rule id.

Body (application/json)

NameTypeRequiredDescription
namestringnoWhat the rule is for. At most 100 characters.
from_patternstring or nullnoSender glob, or null.
subject_patternstring or nullnoSubject glob, or null.
actionstringnoWhat to do with a match. One of forward, delete, label.
action_valuestring or nullnoForward address or label name.
enabledbooleannoWhether it runs.
priorityintegernoHigher runs first. 0 to 100.
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}'

Response 200

JSON
{
  "success": true
}

Delete a rule

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

Deletes the rule.

Path parameters

NameDescription
idThe rule id.
curl -X DELETE "https://api.dissolve.email/v1/rules/$RULE_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