Mailbox Contact Rules

Per-mailbox allow/block rules for inbound email. The mailbox's filter_mode field decides how the rule list is interpreted:

• filter_mode: "whitelist" — only senders matching an allow rule can deliver mail
• filter_mode: "blacklist" — every sender can deliver except those matching a block rule

Set filter_mode on the mailbox itself via PATCH /mailboxes/{email_address} — see Mailboxes. The rules below are interpreted against that mode.

Rules match on either a full email address (match_type: "exact_email") or a bare domain (match_type: "domain"). A rule with status: "paused" reserves the target slot without taking effect, so you can stage policy changes without losing the uniqueness claim.

Auth. List, get, and create accept admin API keys, claimed agent keys, and Clerk JWT; unclaimed (mid-signup) agent keys are rejected. PATCH, DELETE, and the org-wide list are admin + JWT only.

For the org-wide audit view, see List org mail contact rules.

GET /mailboxes/{email_address}/contact-rules

List contact rules for a mailbox, newest first. Returns both active and paused rules.

Path parameters

Query parameters

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

POST /mailboxes/{email_address}/contact-rules

Create an allow or block rule on a mailbox.

Path parameters

Request body

New rules always start with status: "active" — to pause a rule use Update contact rule.

Request example

JSON

Response (201)

Returns the created rule.

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /mailboxes/{email_address}/contact-rules/{rule_id}

Fetch a single contact rule by ID.

Path parameters

Code examples

cURL

cURL

JavaScript

Python

PATCH /mailboxes/{email_address}/contact-rules/{rule_id}

Update a rule's action or status.

Auth: admin API key or Clerk JWT only.

match_type and match_target are immutable — delete the rule and create a new one to change the target.

Path parameters

Request body

At least one of:

Sending null for either field is a client error (422) — omit the field to leave it unchanged.

Code examples

cURL

cURL

JavaScript

Python

DELETE /mailboxes/{email_address}/contact-rules/{rule_id}

Delete a contact rule. Returns 204 No Content on success.

Auth: admin API key or Clerk JWT only.

Path parameters

Code examples

cURL

cURL

JavaScript

Python

GET /mail/contact-rules

Org-wide aggregate list of mail contact rules across every mailbox the caller can see. Intended for admin dashboards that render rules org-wide without fanning out one per-mailbox request per mailbox.

Auth: admin API key or Clerk JWT only.

Results are ordered created_at descending, with id as a stable tiebreaker so pagination stays consistent when rules from different mailboxes share a microsecond.

Query parameters

Response (200)

Returns an array of contact rule objects — same shape as the per-mailbox list.

Code examples

cURL

cURL

JavaScript

Python

• Filtering guide — narrative walk-through of whitelist/blacklist semantics across mail and phone
• Mailboxes — includes the filter_mode field that interprets these rules
• Phone contact rules — the phone-side equivalent