iMessage Contact Rules

iMessage uses the identity’s shared phone communication list, covering incoming and outgoing iMessage, SMS/MMS, and calls. These routes remain supported alongside the phone rule routes and contact permission edits; all change the same exact-number choices. For a shared policy, set phone_filter_mode or its imessage_filter_mode alias and omit rule direction. New rules then apply to both directions. An active applicable allow or block takes precedence in either mode. Numbers without an applicable choice follow the direction’s mode:

imessage_filter_mode: "whitelist": unmatched numbers are denied.
imessage_filter_mode: "blacklist": unmatched numbers are permitted.

Use phone_inbound_filter_mode and phone_outbound_filter_mode on the identity for independent defaults. There is no separate iMessage directional mode pair. Inbound is from the external party to the agent; outbound is from the agent to that party. Only rules covering the relevant direction apply. See Manage identities. Rules match exact E.164 phone numbers (match_type: "exact_number"). New directional SDK/CLI options require 0.7.3 or later.

Direction and rule identity

Companion mode supports conversation-only sponsorship in eligible dedicated-line groups. It does not change shared-line connections or global number permissions. An applicable block on any group participant vetoes Companion permission in that direction. An eligible introducing sender needs active exact-number allows in both directions under the shared phone policy. Defaults or access to another Companion conversation do not qualify. Their own authenticated message in the verified group activates the scope; merely appearing in its participant list does not.

Create defaults to direction: "both". PATCH without direction preserves coverage.
List direction=inbound or outbound includes both rules. direction=both selects only bidirectional rules. Omit direction for all rules without duplicates. Action and match-type filters apply independently before pagination. A2A filters remain exact matches with their existing defaults.
Compatible new coverage widens the existing rule to both. Matching actions and lifecycle states consolidate even after editing two existing rules. Previously issued IDs remain usable for get, update, and delete of the consolidated logical rule. Lists include it once; an ID does not permanently denote its original direction.
POST returns 201, including widening. Use the returned ID and direction; a new ID is not guaranteed. PATCH returns 200.
Duplicate coverage returns 409 with rule_already_exists and existing_rule_id. Conflicting actions also return 409; create does not overwrite them. Paused coverage is not silently reactivated or combined with active coverage.
A both rule has one action. Use separate one-way rules for opposing actions. Inbound permission does not imply permission to reply.

When neither ordinary nor valid Companion permission allows a message, it is not delivered to the agent. When outbound permission is denied, sends return 403. Review message listing for blocked-message access.

Shared-line connections

Establishing or re-establishing a shared-line connection requires effective inbound and outbound permission for that person, along with the existing setup requirements. Defaults can supply those permissions; an explicit both rule is not required. Connecting never adds an allow rule, widens a rule, or changes a mode. An existing connection is not automatically disconnected when rules change. Subsequent traffic checks its own direction; reconnecting checks both again. Dedicated-line traffic keeps per-direction checks rather than inheriting the shared-line setup requirement. Sending still requires consent and a ready channel. Auth. Claimed agent keys can read their permitted rules. Creating, updating, or deleting rules requires an admin API key or the Inkbox Console. Agent writes return 403. Org-wide listings require administrative access.

List contact rules

GET /identities/{agent_handle}/contact-rules

List contact rules for an agent identity, newest first. An identity-scoped API key may read only its own identity’s agent_handle. Another handle returns 403; agent keys cannot create rules.

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"`
`direction`	string	All	`"inbound"` or `"outbound"` includes `"both"`; `"both"` is exact
`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",
    "direction": "both",
    "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)
`direction`	string	No	`"inbound"`, `"outbound"`, or `"both"` (default); null is invalid

Request example

JSON

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

Response (201)

Returns the saved rule, which may be an existing rule widened to both. See Contact rule object.

Error responses

Status	Description
403	Creating rules requires an admin API key or the Inkbox Console; agent keys cannot create rules for any identity
404	Identity not found, or not visible to the caller
409	Duplicate coverage (`rule_already_exists`, including `existing_rule_id`) or conflicting coverage for the same number
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 action or coverage, or atomically edit one covered side. Requires an admin API key, or manage rules from the Inkbox Console. Match type and target are immutable.

Path parameters

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

Request body

Supply action, direction, or both. apply_to requires action and excludes direction. Supplied values cannot be null.

Field	Type	Required	Description
`action`	string	Conditional	`"allow"` or `"block"`; required with `apply_to`
`direction`	string	No	`"inbound"`, `"outbound"`, or `"both"`; changes coverage
`apply_to`	string	No	`"inbound"` or `"outbound"`; change only that covered side’s action atomically

Request example

JSON

{
  "action": "allow"
}

Response (200)

Returns the updated rule. On a both allow, {"action":"block","apply_to":"inbound"} blocks inbound and preserves outbound allow atomically. Refresh the list to see the preserved opposite-side rule; the response contains the addressed rule. Applying the current action does not split it. In contrast, {"direction":"inbound"} removes outbound coverage and lets remaining rules and the outbound default decide sending permission. An action-only PATCH changes all current coverage.

updated = inkbox.imessage_contact_rules.update(
    "my-agent", rule_id, action="block", apply_to="inbound",
)

import { IMessageRuleAction } from "@inkbox/sdk";

const updated = await inkbox.imessageContactRules.update("my-agent", ruleId, {
  action: IMessageRuleAction.BLOCK, applyTo: "inbound",
});

inkbox imessage contact-rule update RULE_ID -i my-agent --action block --apply-to inbound
inkbox imessage contact-rule list -i my-agent --direction outbound

Error responses

Status	Description
403	Caller is not admin-scoped
404	Rule not found, or it belongs to a different identity
409	The requested coverage conflicts with another rule
422	Empty update, null or invalid value, or `apply_to` without action, with direction, set to `both`, or selecting an uncovered side

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
`direction`	string	All	`"inbound"` or `"outbound"` includes `"both"`; `"both"` is exact
`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

List, get, create, update, and organization-wide list responses include a nullable contact card for an exact target with one resolved owner in the rule’s organization. The card follows the caller’s contact permissions and contains no memories, memory_count, or latest_memory. Unresolved, ambiguous, and inaccessible matches return null. Reads resolve the current contact. An idempotent write replay preserves its original response snapshot. SDK/CLI 0.6.11 supports these cards; CLI tables show contact names and JSON output preserves the card.

Field	Type	Description
`contact`	object or null	Authorized matching contact card, without memories
`id`	string (UUID)	Rule ID
`agent_identity_id`	string (UUID)	The identity this rule protects
`action`	string	`"allow"` or `"block"`
`direction`	string	`"inbound"`, `"outbound"`, or `"both"`
`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. Status cannot be changed through PATCH.
`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: alternative routes for the same phone communication list

​Direction and rule identity

​Shared-line connections

​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

Direction and rule identity

Shared-line connections

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