iMessage Contact Rules

Per-identity allow/block rules for inbound iMessage traffic. Rules attach to the agent identity and are addressed by agent_handle, whether the identity uses shared service or an attached dedicated line. 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. Creating a duplicate rule for the same number 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.

List contact rules

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

Parameter	Type	Description
`agent_handle`	string	The identity’s handle, with or without the leading `@`

Query parameters

Parameter	Type	Default	Description
`action`	string	—	Filter by `"allow"` or `"block"`
`match_type`	string	—	Filter by match type (`"exact_number"` is the only value in v1)
`limit`	integer	50	1–200
`offset`	integer	0	Offset for pagination

Response (200)

JSON

[
  {
    "id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "action": "block",
    "match_type": "exact_number",
    "match_target": "+15555550999",
    "status": "active",
    "created_at": "2026-06-09T12:30:00Z",
    "updated_at": "2026-06-09T12:30:00Z"
  }
]

Code examples

curl "https://inkbox.ai/api/v1/imessage/identities/my-agent/contact-rules" \
  -H "X-API-Key: YOUR_API_KEY"

rules = inkbox.imessage_contact_rules.list("my-agent")
for rule in rules:
    print(rule.action, rule.match_target, rule.status)

const rules = await inkbox.imessageContactRules.list("my-agent");
for (const rule of rules) {
  console.log(rule.action, rule.matchTarget, rule.status);
}

Create contact rule

POST /identities/{agent_handle}/contact-rules

Add an allow or block rule for an agent identity. New rules are always created active.

Path parameters

Parameter	Type	Description
`agent_handle`	string	The identity’s handle

Request body

Field	Type	Required	Description
`action`	string	Yes	`"allow"` or `"block"`
`match_target`	string	Yes	Phone number to match, normalized to E.164
`match_type`	string	No	Defaults to `"exact_number"` (the only value in v1)

Request example

JSON

{
  "action": "block",
  "match_target": "+15555550999"
}

Response (201)

Returns the new rule. See Contact rule object.

Error responses

Status	Description
403	Identity-scoped key addressed a different identity’s handle
404	Identity not found, or not visible to the caller
409	`rule_already_exists` — a rule with the same `(match_type, match_target)` already exists on this identity; the response includes `existing_rule_id`
422	Invalid `action`, `match_type`, or `match_target`

Code examples

curl -X POST "https://inkbox.ai/api/v1/imessage/identities/my-agent/contact-rules" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "block", "match_target": "+15555550999"}'

rule = inkbox.imessage_contact_rules.create(
    "my-agent",
    action="block",
    match_target="+15555550999",
)

const rule = await inkbox.imessageContactRules.create("my-agent", {
  action: "block",
  matchTarget: "+15555550999",
});

Get contact rule

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

Fetch a single rule by ID.

Path parameters

Parameter	Type	Description
`agent_handle`	string	The identity’s handle
`rule_id`	UUID	Rule ID

Response (200)

Returns the rule. See Contact rule object.

Error responses

Status	Description
403	Identity-scoped key addressed a different identity’s handle
404	Rule not found, or it belongs to a different identity

Update contact rule

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

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

Path parameters

Parameter	Type	Description
`agent_handle`	string	The identity’s handle
`rule_id`	UUID	Rule ID

Request body

action is required.

Field	Type	Required	Description
`action`	string	Yes	`"allow"` or `"block"`

Request example

JSON

{
  "action": "allow"
}

Response (200)

Returns the updated rule.

Error responses

Status	Description
403	Caller is not admin-scoped
404	Rule not found, or it belongs to a different identity
422	`action` is missing, null, or invalid

Delete contact rule

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

Parameter	Type	Description
`agent_handle`	string	The identity’s handle
`rule_id`	UUID	Rule ID

Response (204)

No content.

Error responses

Status	Description
403	Caller is not admin-scoped
404	Rule not found, or it belongs to a different identity

List org iMessage contact rules

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

Parameter	Type	Default	Description
`agent_identity_id`	UUID	—	Narrow to one identity by ID
`action`	string	—	Filter by `"allow"` or `"block"`
`match_type`	string	—	Filter by match type (`"exact_number"` is the only value in v1)
`limit`	integer	50	1–200
`offset`	integer	0	Offset for pagination

Response (200)

Returns a list[ContactRule] ordered newest first.

Code examples

curl "https://inkbox.ai/api/v1/imessage/contact-rules?action=block" \
  -H "X-API-Key: YOUR_API_KEY"

rules = inkbox.imessage_contact_rules.list_all(action="block")

const rules = await inkbox.imessageContactRules.listAll({ action: "block" });

Contact rule object

Field	Type	Description
`id`	string (UUID)	Rule ID
`agent_identity_id`	string (UUID)	The identity this rule protects
`action`	string	`"allow"` or `"block"`
`match_type`	string	`"exact_number"` (the only value in v1)
`match_target`	string	The matched phone number in E.164 format
`status`	string	`"active"`; existing rules may return `"paused"` as a read-only compatibility value. Update requests accept only `action`.
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Additional resources

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

​List contact rules

​Path parameters

​Query parameters

​Response (200)

​Code examples

​Create contact rule

​Path parameters

​Request body

​Request example

​Response (201)

​Error responses

​Code examples

​Get contact rule

​Path parameters

​Response (200)

​Error responses

​Update contact rule

​Path parameters

​Request body

​Request example

​Response (200)

​Error responses

​Delete contact rule

​Path parameters

​Response (204)

​Error responses

​List org iMessage contact rules

​Query parameters

​Response (200)

​Code examples

​Contact rule object

​Additional resources

List contact rules

Path parameters

Query parameters

Response (200)

Code examples

Create contact rule

Path parameters

Request body

Request example

Response (201)

Error responses

Code examples

Get contact rule

Path parameters

Response (200)

Error responses

Update contact rule

Path parameters

Request body

Request example

Response (200)

Error responses

Delete contact rule

Path parameters

Response (204)

Error responses

List org iMessage contact rules

Query parameters

Response (200)

Code examples

Contact rule object

Additional resources