Mail Rules & Policy

curl -X GET "https://api.wirebox.sh/api/v1/identities/eva/mail-rules?direction=inbound" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

from wirebox import Wirebox

with Wirebox() as wirebox:
    eva = wirebox.get_identity("eva")
    result = eva.mail_rules.list(direction="inbound")
    for rule in result.rules:
        print(f"[{rule.action}] {rule.entry} ({rule.direction})")

import { Wirebox } from "@wirebox-sh/sdk";

const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");
const { rules } = await eva.mailRules.list({ direction: "inbound" });

for (const rule of rules) {
  console.log(`[${rule.action}] ${rule.entry} (${rule.direction})`);
}

wirebox mail rules list --identity eva --direction inbound

{
  "id": "<string>",
  "agent_handle": "<string>",
  "direction": "<string>",
  "action": "<string>",
  "entry": "<string>",
  "match_type": "<string>",
  "match_target": "<string>",
  "reason": {},
  "status": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>"
}

GET

api

identities

{agent_handle}

mail-rules

curl -X GET "https://api.wirebox.sh/api/v1/identities/eva/mail-rules?direction=inbound" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

from wirebox import Wirebox

with Wirebox() as wirebox:
    eva = wirebox.get_identity("eva")
    result = eva.mail_rules.list(direction="inbound")
    for rule in result.rules:
        print(f"[{rule.action}] {rule.entry} ({rule.direction})")

import { Wirebox } from "@wirebox-sh/sdk";

const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");
const { rules } = await eva.mailRules.list({ direction: "inbound" });

for (const rule of rules) {
  console.log(`[${rule.action}] ${rule.entry} (${rule.direction})`);
}

wirebox mail rules list --identity eva --direction inbound

{
  "id": "<string>",
  "agent_handle": "<string>",
  "direction": "<string>",
  "action": "<string>",
  "entry": "<string>",
  "match_type": "<string>",
  "match_target": "<string>",
  "reason": {},
  "status": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>"
}

Mail rules are per-identity allow/block lists that control which emails reach an agent’s inbox (inbound), which addresses it may send to (outbound), replies on existing threads (reply), or both. A rule’s entry is either an exact email address (alex@example.com) or a domain (example.com). Rules take precedence over the baseline filter modes. For an inbound message, Wirebox evaluates:

Exact-email rule (match_type: exact_email)
Domain rule (match_type: domain)
Reply on an existing outbound thread (reply direction rules)
Baseline inbound filter mode

Rule Object

string

Unique rule identifier (mrl_ prefix).

string

Identity the rule belongs to.

string

inbound, outbound, reply, or both.

string

allow or block.

string

Normalized match target (email address or domain).

string

exact_email for addresses, domain for domains.

string

Same value as entry; kept for API symmetry.

string | null

Optional audit note describing why the rule exists.

string

active or paused.

string

ISO 8601 creation timestamp.

string

ISO 8601 update timestamp.

List Rules

Path Parameters

string

required

The agent handle (e.g. eva).

Query Parameters

string

Filter by direction: inbound, outbound, or both. Rules with direction both are included when filtering for a specific direction.

The response also carries the identity’s current baseline filter_modes:

{
  "rules": [
    {
      "id": "mrl_01J8ABC123XYZ",
      "agent_handle": "eva",
      "direction": "inbound",
      "action": "allow",
      "entry": "partner.example",
      "match_type": "domain",
      "match_target": "partner.example",
      "reason": "Trusted partner domain",
      "status": "active",
      "created_at": "2026-10-06T10:00:00Z",
      "updated_at": "2026-10-06T10:00:00Z"
    }
  ],
  "filter_modes": {
    "inbound": "whitelist",
    "outbound": "blacklist"
  }
}

curl -X GET "https://api.wirebox.sh/api/v1/identities/eva/mail-rules?direction=inbound" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

from wirebox import Wirebox

with Wirebox() as wirebox:
    eva = wirebox.get_identity("eva")
    result = eva.mail_rules.list(direction="inbound")
    for rule in result.rules:
        print(f"[{rule.action}] {rule.entry} ({rule.direction})")

import { Wirebox } from "@wirebox-sh/sdk";

const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");
const { rules } = await eva.mailRules.list({ direction: "inbound" });

for (const rule of rules) {
  console.log(`[${rule.action}] ${rule.entry} (${rule.direction})`);
}

wirebox mail rules list --identity eva --direction inbound

Create Rule

Body Parameters

string

required

Email address or domain to match. Contains @ → treated as an exact address; otherwise treated as a domain (a leading @ or *@ is stripped).

string

required

allow or block.

string

default:"both"

inbound, outbound, reply, or both.

string

Optional audit note.

Returns 201 with the created Rule Object. Creating a duplicate rule for the same target and direction is rejected with 409.

curl -X POST "https://api.wirebox.sh/api/v1/identities/eva/mail-rules" \
  -H "Authorization: Bearer $WIREBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entry": "partner.example",
    "action": "allow",
    "direction": "inbound",
    "reason": "Trusted partner domain"
  }'

from wirebox import Wirebox

with Wirebox() as wirebox:
    eva = wirebox.get_identity("eva")
    rule = eva.mail_rules.allow("partner.example", direction="inbound")
    print("Rule ID:", rule.id)

import { Wirebox } from "@wirebox-sh/sdk";

const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");
const rule = await eva.mailRules.allow("partner.example", { direction: "inbound" });
console.log("Rule ID:", rule.id);

wirebox mail rules allow partner.example \
  --identity eva \
  --inbound \
  --reason "Trusted partner domain"

Get, Update & Delete a Rule

GET /identities/{agent_handle}/mail-rules/{rule_id} returns a single Rule Object. PATCH accepts any of direction, action, status (active or paused), and reason, and returns the updated rule:

cURL

curl -X PATCH "https://api.wirebox.sh/api/v1/identities/eva/mail-rules/mrl_01J8ABC123XYZ" \
  -H "Authorization: Bearer $WIREBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

DELETE /identities/{agent_handle}/mail-rules/{rule_id} removes the rule and returns 204 No Content:

cURL

curl -X DELETE "https://api.wirebox.sh/api/v1/identities/eva/mail-rules/mrl_01J8ABC123XYZ" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

CLI

wirebox mail rules remove mrl_01J8ABC123XYZ --identity eva

Filter Modes (Policy)

Every identity also has a baseline posture for each direction, stored as mail_inbound_filter_mode and mail_outbound_filter_mode (see Update Agent Identity):

Mode	Inbound	Outbound
`whitelist`	Only approved senders (explicit rules or ongoing threads) are admitted; everything else is quarantined	Only approved recipients may receive mail
`blacklist`	Open to anyone except blocked rules	No recipient restrictions beyond blocked rules

The SDKs expose the same settings with friendlier names: protected (= whitelist) or open (= blacklist) for inbound, and restricted (= whitelist) or open (= blacklist) for outbound.

from wirebox import Wirebox

with Wirebox() as wirebox:
    eva = wirebox.get_identity("eva")

    print(eva.mail_policy)  # MailPolicy(inbound='open', outbound='open')

    eva.set_mail_policy(inbound="protected", outbound="restricted")

import { Wirebox } from "@wirebox-sh/sdk";

const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");

console.log(await eva.mailRules.getPolicy()); // { inbound: "open", outbound: "open" }

await eva.mailRules.setPolicy({ inbound: "protected", outbound: "restricted" });

# Read the current posture
wirebox mail policy get --identity eva

# Require approved senders and recipients
wirebox mail policy set --identity eva --inbound protected --outbound restricted

Overview

Agent Identities

Mail

Domains

Phone

iMessage

Network Tunnels

Webhooks

Mail Rules & Policy

Rule Object

List Rules

Path Parameters

Query Parameters

Create Rule

Body Parameters

Get, Update & Delete a Rule

Filter Modes (Policy)

​Rule Object

​List Rules

​Path Parameters

​Query Parameters

​Create Rule

​Body Parameters

​Get, Update & Delete a Rule

​Filter Modes (Policy)

Rule Object

List Rules

Path Parameters

Query Parameters

Create Rule

Body Parameters

Get, Update & Delete a Rule

Filter Modes (Policy)