Mail Contact Rules

Mail rules govern incoming and outgoing email. They attach to the agent identity and are addressed by agent_handle. For a shared policy, set mail_filter_mode and omit rule direction: new rules apply to both sending and receiving. Contact permission edits and standalone exact-email rules change the same choices.

whitelist: a matching allow domain permits communication; otherwise it is denied.
blacklist: a matching block domain denies communication; otherwise it is permitted.

An active exact-email allow or block takes precedence over domains and defaults in either mode. Evaluate only rules covering the communication’s direction. Inbound is from the external party to the agent; outbound is from the agent to that party. Use mail_inbound_filter_mode and mail_outbound_filter_mode for independent defaults. See Manage identities and the split-mode example. New directional SDK/CLI options require 0.7.3 or later. Receiving permission does not permit a reply. Sending permission does not permit receiving, and does not replace other send requirements. Companion mode can permit a sponsored email conversation without globally allowing every participant. An applicable explicit block anywhere in its exact participant cohort vetoes Companion permission in that direction, after exact-address-over-domain precedence. Separate recipient branches need separate sponsorship. To be eligible to activate a group, the actual sender address needs active exact_email allows covering both inbound and outbound. One both allow and two one-way allows are equivalent. Domain allows and access from blacklist defaults do not make a sender eligible. Their qualifying authenticated message, not the rule alone, activates the scope.

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").

Direction and rule identity

Create defaults to direction: "both". PATCH without direction preserves current coverage.
List with direction=inbound or outbound includes matching one-way rules and both rules. direction=both selects only bidirectional rules. Omit the filter for all rules without duplicates. Action and match-type filters apply independently, before pagination. A2A direction filters remain exact matches with their existing defaults.
One both rule has one action. Opposite actions require separate inbound and outbound rules.
Adding compatible coverage for the same target 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 contain it once. An ID does not permanently identify its original direction.
Successful POST returns 201, including widening an existing rule. Use the returned ID and direction; success does not guarantee a new ID. PATCH returns 200.
Creating coverage that already exists returns 409, with the existing duplicate error 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.

These semantics also apply to the deprecated mailbox routes. When a sender is blocked, inbound mail is stored but never delivered to the agent, and no message.received webhook fires. 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}/mail-contact-rules

List mail 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"` selects only bidirectional rules
`match_type`	string	—	Filter by `"exact_email"` or `"domain"`
`limit`	integer	50	Max rules (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": "domain",
    "match_target": "spam.example",
    "status": "active",
    "created_at": "2026-04-21T12:30:00Z",
    "updated_at": "2026-04-21T12:30:00Z"
  }
]

Code examples

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

const response = await fetch(
  `https://inkbox.ai/api/v1/identities/${agentHandle}/mail-contact-rules`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const rules = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/identities/{agent_handle}/mail-contact-rules",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
rules = response.json()

Create contact rule

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

Create an allow or block rule on an agent identity. New rules always start 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_type`	string	Yes	`"exact_email"` (full address) or `"domain"` (bare domain like `example.com`)
`match_target`	string	Yes	Value to match against. For `exact_email`: a full address with one `@` and at least one dot after it. For `domain`: a lowercase ASCII bare domain (no leading `*@`, no leading `@`, no trailing `.`). Max 320 chars.
`direction`	string	No	`"inbound"`, `"outbound"`, or `"both"` (default); null is invalid

Request example

JSON

{
  "action": "block",
  "match_type": "domain",
  "match_target": "spam.example"
}

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 target
422	`match_target` invalid for the given `match_type` (e.g. glob pattern, non-ASCII domain, missing dot)

Code examples

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

const response = await fetch(
  `https://inkbox.ai/api/v1/identities/${agentHandle}/mail-contact-rules`,
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          action: "block",
          match_type: "domain",
          match_target: "spam.example",
      }),
  }
);
const rule = await response.json();

import requests

response = requests.post(
    f"https://inkbox.ai/api/v1/identities/{agent_handle}/mail-contact-rules",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "action": "block",
        "match_type": "domain",
        "match_target": "spam.example",
    },
)
rule = response.json()

Get contact rule

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

Fetch a single contact 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

Code examples

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

const response = await fetch(
  `https://inkbox.ai/api/v1/identities/${agentHandle}/mail-contact-rules/${ruleId}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const rule = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/identities/{agent_handle}/mail-contact-rules/{rule_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
rule = response.json()

Update contact rule

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

Change a rule’s action or coverage, or atomically edit one covered side. 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

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 cannot be combined with 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, rather than selecting a side to edit
`apply_to`	string	No	`"inbound"` or `"outbound"`; changes only that covered side’s action, preserving the opposite side atomically

Request example

JSON

{
  "action": "allow"
}

Response (200)

Returns the updated rule.

Change one side without removing the other

For a rule that allows both, this request blocks inbound and retains outbound allow in one operation:

{"action": "block", "apply_to": "inbound"}

The response contains the addressed inbound rule. Refresh the list to see the preserved outbound rule. Applying the existing action does not split the rule. An uncovered side, apply_to: "both", missing action, null, or a combination with direction returns 422. By contrast, {"direction":"inbound"} on a both rule removes outbound coverage. The outbound mode and remaining applicable rules then determine sending permission. An action-only PATCH changes every direction currently covered by that rule.

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

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

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

use inkbox::{ContactRuleApplyTo, ContactRuleUpdateOptions};
use inkbox::mail::MailRuleAction;

let updated = inkbox.mail_identity_contact_rules().update_with_options(
    "my-agent", rule_id,
    &ContactRuleUpdateOptions {
        action: Some(MailRuleAction::Block),
        apply_to: Some(ContactRuleApplyTo::Inbound),
        ..Default::default()
    },
)?;
println!("{} {:?}", updated.rule.id, updated.direction);

inkbox identity mail-rules update my-agent RULE_ID --action block --apply-to inbound

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, invalid or null value, or invalid `apply_to` combination or uncovered side

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/identities/my-agent/mail-contact-rules/RULE_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "allow"}'

const response = await fetch(
  `https://inkbox.ai/api/v1/identities/${agentHandle}/mail-contact-rules/${ruleId}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ action: "allow" }),
  }
);
const rule = await response.json();

import requests

response = requests.patch(
    f"https://inkbox.ai/api/v1/identities/{agent_handle}/mail-contact-rules/{rule_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"action": "allow"},
)
rule = response.json()

Delete contact rule

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

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

Error responses

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

Code examples

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

await fetch(
  `https://inkbox.ai/api/v1/identities/${agentHandle}/mail-contact-rules/${ruleId}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

requests.delete(
    f"https://inkbox.ai/api/v1/identities/{agent_handle}/mail-contact-rules/{rule_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

List org mail contact rules

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 grouped by matched contact ID, with rules that have no matched contact last. Within each group, rules are ordered by created_at descending and then id ascending. Grouping happens before pagination, and a contact’s rows can span adjacent pages.

Query parameters

Parameter	Type	Default	Description
`agent_identity_id`	UUID	—	Narrow to one identity by ID; omit to list across every identity in the org
`direction`	string	All	`"inbound"` or `"outbound"` includes `"both"`; `"both"` selects only bidirectional rules
`action`	string	—	Filter by `"allow"` or `"block"`
`match_type`	string	—	Filter by `"exact_email"` or `"domain"`
`limit`	integer	50	Max rules (1–200)
`offset`	integer	0	Offset for pagination

Response (200)

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

Code examples

curl -X GET "https://inkbox.ai/api/v1/mail/contact-rules?action=block&limit=100" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY"

const response = await fetch(
  "https://inkbox.ai/api/v1/mail/contact-rules?action=block&limit=100",
  { headers: { "X-API-Key": "YOUR_ADMIN_API_KEY" } }
);
const rules = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/mail/contact-rules",
    headers={"X-API-Key": "YOUR_ADMIN_API_KEY"},
    params={"action": "block", "limit": 100},
)
rules = response.json()

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. Domain, unresolved, ambiguous, and inaccessible matches return null. Hidden profile fields and identifiers are not restored by reading a rule. 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`	UUID	Unique rule identifier
`agent_identity_id`	UUID	The identity this rule protects
`action`	string	`"allow"` or `"block"`
`direction`	string	`"inbound"`, `"outbound"`, or `"both"`
`match_type`	string	`"exact_email"` or `"domain"`
`match_target`	string	Canonicalized match value
`status`	string	`"active"`; existing rules may return `"paused"` as a read-only compatibility value. Status cannot be changed through PATCH.
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last-updated timestamp (ISO 8601)

Additional resources

Email guide — Filtering inbound mail — narrative walk-through of whitelist/blacklist semantics
Manage identities — set mail_filter_mode
iMessage contact rules: the shared phone list for SMS, calls, and iMessage
Phone contact rules — the phone-side equivalent for calls and texts

​Direction and rule identity

​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

​Code examples

​Update contact rule

​Path parameters

​Request body

​Request example

​Response (200)

​Change one side without removing the other

​Error responses

​Code examples

​Delete contact rule

​Path parameters

​Error responses

​Code examples

​List org mail contact rules

​Query parameters

​Response (200)

​Code examples

​Contact rule object

​Additional resources

Direction and rule identity

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

Code examples

Update contact rule

Path parameters

Request body

Request example

Response (200)

Change one side without removing the other

Error responses

Code examples

Delete contact rule

Path parameters

Error responses

Code examples

List org mail contact rules

Query parameters

Response (200)

Code examples

Contact rule object

Additional resources