iMessage Contact Rules

Per-identity allow/block rules for inbound iMessage traffic. Because there is no per-identity iMessage number — conversations ride a shared pool of lines — rules attach to the agent identity itself and are addressed by agent_handle. The identity's imessage_filter_mode field decides how the rule list is interpreted:

• imessage_filter_mode: "whitelist" — only numbers matching an allow rule can reach the agent
• imessage_filter_mode: "blacklist" — every number can reach the agent except those matching a block rule

Set imessage_filter_mode on the identity via PATCH /identities/{agent_handle} — see Manage identities. Rules match on exact E.164 phone numbers only in v1 (match_type: "exact_number"); the field is wired in to stay forward-compatible when additional match types are added.

A rule with status: "paused" has no effect, but still counts as the rule for its number. Creating a duplicate returns 409.

When a number is blocked: inbound messages are stored but never delivered to the agent. No webhooks fire, identity-scoped keys never see them, and admin API keys or the Inkbox Console can audit them with is_blocked=true. Inbound tapbacks are not recorded, outbound sends and tapbacks to the number return 403, and the router gives the blocked human the same generic response as for an unknown agent.

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}/contact-rules

List contact rules for an agent identity, newest first.

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

Python

TypeScript

POST /identities/{agent_handle}/contact-rules

Add an allow or block rule for an agent identity. New rules are always created active; use update to pause one.

Path parameters

Request body

Request example

JSON

Response (201)

Returns the new rule. See Contact rule object.

Error responses

Code examples

cURL

cURL

Python

TypeScript

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

Fetch a single rule by ID.

Path parameters

Response (200)

Returns the rule. See Contact rule object.

Error responses

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

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

Path parameters

Request body

At least one field is required; fields you omit are left unchanged.

Request example

JSON

Response (200)

Returns the updated rule.

Error responses

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

Delete a rule. Requires an admin API key, or manage rules from the Inkbox Console.

Path parameters

Response (204)

No content.

Error responses

GET /contact-rules

Org-wide aggregate list of iMessage contact rules across every identity. Requires an admin API key, or browse rules in the Inkbox Console.

Query parameters

Response (200)

Returns a list[ContactRule] ordered newest first.

Code examples

cURL

cURL

Python

TypeScript

• iMessage guide — filtering
• Manage identities — set imessage_filter_mode
• Phone contact rules — the per-number equivalent for calls and texts