Mailbox Rules

Label or archive new inbound conversations automatically, based on sender or subject.

Mailbox rules automatically process inbound messages as they arrive. Each rule defines a condition (what to match) and an action (what to do). Rules run in priority order and can optionally stop processing further rules when matched.

Rules are managed via the Agent Runtime API using your Bearer token.

Create a rule

POST https://agentic-mailbox.molted.email/v1/rules?tenantId=YOUR_TENANT_ID

curl

curl -X POST "https://agentic-mailbox.molted.email/v1/rules?tenantId=YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mailboxId": "MAILBOX_UUID",
    "name": "Archive newsletters",
    "conditionType": "sender_domain",
    "conditionOperator": "ends_with",
    "conditionValue": "newsletter.example.com",
    "actionType": "auto_archive",
    "enabled": true,
    "stopProcessing": false
  }'

Response

{
  "id": "rule_uuid",
  "mailboxId": "MAILBOX_UUID",
  "name": "Archive newsletters",
  "conditionType": "sender_domain",
  "conditionOperator": "ends_with",
  "conditionValue": "newsletter.example.com",
  "actionType": "auto_archive",
  "actionValue": null,
  "enabled": true,
  "position": 0,
  "stopProcessing": false
}

Condition types

Type	Matches against
`sender_domain`	The domain portion of the sender's email address.
`sender_email`	The full sender email address.
`subject`	The message subject line.

Condition operators

Operator	Description
`equals`	Exact match (case-insensitive).
`contains`	Substring match.
`matches_pattern`	Glob-style pattern match.
`ends_with`	Suffix match.

Actions

Action	`actionValue`	Description
`apply_label`	Label ID	Apply a label of the same mailbox to the new thread, recorded as applied by the rule (`appliedBy: { "type": "rule" }`).
`move_to_folder`	Label ID	The old name of `apply_label`; still works.
`auto_archive`	Not required	Archive the message immediately.

Request fields

Field	Type	Required	Description
`mailboxId`	`string`	Yes	UUID of the mailbox to attach the rule to.
`name`	`string`	Yes	Human-readable label for the rule.
`conditionType`	`string`	Yes	What to match against.
`conditionOperator`	`string`	Yes	How to compare.
`conditionValue`	`string`	Yes	The value to compare against.
`actionType`	`string`	Yes	What to do when the condition matches.
`actionValue`	`string`	No	The label ID, for `apply_label` (it must be a label of the rule's mailbox).
`enabled`	`boolean`	No	Whether the rule is active. Defaults to `true`.
`position`	`integer`	No	Sort order. Lower values run first.
`stopProcessing`	`boolean`	No	Stop evaluating further rules when this one matches. Defaults to `false`.

List rules

GET https://agentic-mailbox.molted.email/v1/rules?tenantId=YOUR_TENANT_ID&mailboxId=MAILBOX_UUID

curl

curl "https://agentic-mailbox.molted.email/v1/rules?tenantId=YOUR_TENANT_ID&mailboxId=MAILBOX_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a rule

GET https://agentic-mailbox.molted.email/v1/rules/:id?tenantId=YOUR_TENANT_ID

Update a rule

PATCH https://agentic-mailbox.molted.email/v1/rules/:id?tenantId=YOUR_TENANT_ID

curl

curl -X PATCH "https://agentic-mailbox.molted.email/v1/rules/RULE_UUID?tenantId=YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

All fields from the create request are optional for updates.

Delete a rule

DELETE https://agentic-mailbox.molted.email/v1/rules/:id?tenantId=YOUR_TENANT_ID

curl

curl -X DELETE "https://agentic-mailbox.molted.email/v1/rules/RULE_UUID?tenantId=YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Reorder rules

Rules are evaluated in ascending position order. Use the reorder endpoint to set the evaluation order explicitly.

POST https://agentic-mailbox.molted.email/v1/rules/reorder?tenantId=YOUR_TENANT_ID

curl

curl -X POST "https://agentic-mailbox.molted.email/v1/rules/reorder?tenantId=YOUR_TENANT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mailboxId": "MAILBOX_UUID",
    "ruleIds": ["rule-uuid-1", "rule-uuid-2", "rule-uuid-3"]
  }'

Rules are assigned positions in the order of the ruleIds array (first element = position 0).

Stop processing

When stopProcessing: true is set on a rule, evaluation halts after the rule matches. This is useful for high-priority rules that should take exclusive action.

Label deletion

Deleting a label automatically disables (does not delete) any rule whose apply_label (or move_to_folder) action targets it. Update the rule to point at a different label, or delete it, once you no longer need it. A matching inbound message is never dropped because of a rule pointing at a deleted label: it still lands in the inbox even if the rule's action can't be applied.

A label applied by a rule is business metadata: it never changes how the message is routed, held or quarantined. A rule labels the thread even when its first message is quarantined or the thread goes to a review queue; the thread.labeled event only fires for a thread your agent can see.

A rule read (list, get, create, update) carries invalidLabel: true and invalidLabelReason when its label can't be applied: label_missing (deleted) or label_in_other_mailbox (a rule made before a rule had to name a label of its own mailbox). Such a rule matches but applies nothing; point it at a label of its own mailbox.

Authorization

Rules require manage scope on the mailbox. Read operations require read scope. See Authentication for key scoping details.

Mailboxes -- create and manage mailboxes
Inbound -- how inbound messages are classified and routed

On this page