Mail Contact Rules

Per-identity allow/block rules for inbound email. Mail rules attach to the agent identity itself and are addressed by agent_handle, mirroring iMessage contact rules. The identity's mail_filter_mode field decides how the rule list is interpreted:

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

Set mail_filter_mode on the identity via PATCH /identities/{agent_handle} — see Manage identities. The rules below are interpreted against that mode.

Deprecation. The previous mailbox-addressed routes (/mailboxes/{email_address}/contact-rules) are deprecated. They still work and return the same fields they did before. Migrate to the identity-keyed routes documented here.

Rules match on either a full email address (match_type: "exact_email") or a bare domain (match_type: "domain"). A rule with status: "paused" has no effect but still reserves its target slot, so you can stage policy changes without losing the uniqueness claim. Creating a duplicate (match_type, match_target) returns 409.

When a sender is blocked, inbound mail is stored but never delivered to the agent, and no message.received webhook fires.

Auth. List, get, and create accept admin API keys and claimed agent keys; unclaimed (mid-signup) agent keys are rejected. PATCH, DELETE, and the org-wide list require an admin-scoped API key, or you can manage them as a user in the Inkbox Console.

GET /identities/{agent_handle}/mail-contact-rules

List mail contact rules for an agent identity, newest first. Returns both active and paused rules.

An identity-scoped API key may only address its own identity's agent_handle — any other handle returns 403 (this applies to list, get, and create alike).

Path parameters

Query parameters

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

POST /identities/{agent_handle}/mail-contact-rules

Create an allow or block rule on an agent identity. New rules always start with status: "active" — to pause a rule use Update contact rule.

Path parameters

Request body

Request example

JSON

Response (201)

Returns the created rule. See Contact rule object.

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /identities/{agent_handle}/mail-contact-rules/{rule_id}

Fetch a single contact rule by ID.

Path parameters

Response (200)

Returns the rule. See Contact rule object.

Error responses

Code examples

cURL

cURL

JavaScript

Python

PATCH /identities/{agent_handle}/mail-contact-rules/{rule_id}

Change a rule's action or status. Requires an admin API key, or manage rules from the Inkbox Console.

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 field is required; fields you omit are left unchanged.

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

Request example

JSON

Response (200)

Returns the updated rule.

Error responses

Code examples

cURL

cURL

JavaScript

Python

DELETE /identities/{agent_handle}/mail-contact-rules/{rule_id}

Delete a contact rule. Returns 204 No Content on success. Requires an admin API key, or manage rules from the Inkbox Console.

Path parameters

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /mail/contact-rules

Org-wide aggregate list of mail contact rules across every identity the caller can see. Intended for admin dashboards that render rules org-wide without fanning out one per-identity request per identity. Requires an admin API key, or browse rules in the Inkbox Console.

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

Query parameters

Response (200)

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

Code examples

cURL

cURL

JavaScript

Python

• Email guide — Filtering inbound mail — narrative walk-through of whitelist/blacklist semantics
• Manage identities — set mail_filter_mode
• iMessage contact rules — the per-identity equivalent for iMessage
• Phone contact rules — the phone-side equivalent for calls and texts