Mailbox Rules

Auto-route, archive, or flag inbound messages based on sender, subject, or other conditions.

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
`move_to_folder`	Folder name	Move the message to the specified folder.
`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	Additional value for the action (e.g., folder name).
`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.

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