Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Filtering
description: Control which senders and callers can reach your mailboxes and phone numbers with whitelist and blacklist rules

---


# Filtering

Keep unwanted senders out of your agents' inboxes and phone numbers. Inkbox combines a **mode** — `whitelist` or `blacklist` — with a list of **contact rules** to decide whether inbound email, calls, and texts are delivered. The concept is identical on both channels; the only differences are what `match_target` can contain.

## How it works

Every mailbox and every phone number has a `filter_mode` field with two values:

- **`blacklist` (default).** Everything is delivered _unless_ a `block` rule matches the sender.
- **`whitelist`.** Nothing is delivered _unless_ an `allow` rule matches the sender.

Mail rules match on `exact_email` (e.g. `jane@acme.example`) or `domain` (e.g. `acme.example`). Phone rules match on `exact_number` — an E.164 phone number. Rules carry an `action` (`allow` or `block`) and a `status` (`active`, `paused`, or `deleted`) — paused rules reserve the target slot without taking effect, which is useful for staging policy changes.

## Choosing a mode

Most agents start in `blacklist` mode: accept everyone, add explicit blocks for spam domains or individual bad actors. Switch a mailbox or number to `whitelist` when you want the opposite — locked down by default, with a known allowlist.

Flip the mode on the mailbox or phone number resource itself:

**Python**

```python
# Switch a mailbox to whitelist mode (admin-only)
inkbox.mailboxes.update("sales.team@inkboxmail.com", filter_mode="whitelist")

# Switch a phone number to whitelist mode (admin-only)
inkbox.phone_numbers.update(phone_number.id, filter_mode="whitelist")

# Back to blacklist (the default)
inkbox.mailboxes.update("sales.team@inkboxmail.com", filter_mode="blacklist")
```

**TypeScript**

```typescript
// Switch a mailbox to whitelist mode (admin-only)
await inkbox.mailboxes.update("sales.team@inkboxmail.com", {
    filterMode: "whitelist",
});

// Switch a phone number to whitelist mode (admin-only)
await inkbox.phoneNumbers.update(phoneNumber.id, {
    filterMode: "whitelist",
});

// Back to blacklist (the default)
await inkbox.mailboxes.update("sales.team@inkboxmail.com", {
    filterMode: "blacklist",
});
```

**CLI**

```bash
# Switch a mailbox to whitelist mode
inkbox mailbox update sales.team@inkboxmail.com --filter-mode whitelist

# Switch a phone number to whitelist mode
inkbox number update <phone-number-id> --filter-mode whitelist
```

## Mail rules

Create allow or block rules scoped to a specific mailbox. Match on an exact email address or a domain (every address at `acme.example`).

**Python**

```python
# Block a single spam sender on this mailbox
inkbox.mail_contact_rules.create(
    "sales.team@inkboxmail.com",
    action="block",
    match_type="exact_email",
    match_target="spammer@spam.example",
)

# Block an entire domain
inkbox.mail_contact_rules.create(
    "sales.team@inkboxmail.com",
    action="block",
    match_type="domain",
    match_target="spam.example",
)

# In whitelist mode: allow one known sender
inkbox.mail_contact_rules.create(
    "sales.team@inkboxmail.com",
    action="allow",
    match_type="exact_email",
    match_target="vendor@acme.example",
)
```

**TypeScript**

```typescript
// Block a single spam sender on this mailbox
await inkbox.mailContactRules.create("sales.team@inkboxmail.com", {
    action: "block",
    matchType: "exact_email",
    matchTarget: "spammer@spam.example",
});

// Block an entire domain
await inkbox.mailContactRules.create("sales.team@inkboxmail.com", {
    action: "block",
    matchType: "domain",
    matchTarget: "spam.example",
});

// In whitelist mode: allow one known sender
await inkbox.mailContactRules.create("sales.team@inkboxmail.com", {
    action: "allow",
    matchType: "exact_email",
    matchTarget: "vendor@acme.example",
});
```

**CLI**

```bash
# Block a single sender
inkbox mailbox rules create --mailbox sales.team@inkboxmail.com \\
  --action block --match-type exact_email --match-target spammer@spam.example

# Block a whole domain
inkbox mailbox rules create --mailbox sales.team@inkboxmail.com \\
  --action block --match-type domain --match-target spam.example

# Allow a sender (useful in whitelist mode)
inkbox mailbox rules create --mailbox sales.team@inkboxmail.com \\
  --action allow --match-type exact_email --match-target vendor@acme.example
```

## Phone rules

Create allow or block rules scoped to a specific phone number. `match_type` must be `exact_number`, and `match_target` is an E.164 phone number.

**Python**

```python
# Block an individual caller
inkbox.phone_contact_rules.create(
    phone_number.id,
    action="block",
    match_target="+15551234567",
)

# In whitelist mode: allow a trusted contact
inkbox.phone_contact_rules.create(
    phone_number.id,
    action="allow",
    match_target="+14445556789",
)
```

**TypeScript**

```typescript
// Block an individual caller
await inkbox.phoneContactRules.create(phoneNumber.id, {
    action: "block",
    matchTarget: "+15551234567",
});

// In whitelist mode: allow a trusted contact
await inkbox.phoneContactRules.create(phoneNumber.id, {
    action: "allow",
    matchTarget: "+14445556789",
});
```

**CLI**

```bash
# Block a caller
inkbox number rules create --number <phone-number-id> \\
  --action block --match-target +15551234567

# Allow a caller (useful in whitelist mode)
inkbox number rules create --number <phone-number-id> \\
  --action allow --match-target +14445556789
```

## Pausing a rule

Flip a rule from `active` to `paused` when you want to disable it without losing the uniqueness claim on the `(match_type, match_target)` slot. Reactivate by setting `status` back to `active`. Use DELETE to remove the rule entirely.

**Python**

```python
# Pause a rule (keeps the slot reserved)
inkbox.mail_contact_rules.update(
    "sales.team@inkboxmail.com", rule_id, status="paused",
)

# Reactivate
inkbox.mail_contact_rules.update(
    "sales.team@inkboxmail.com", rule_id, status="active",
)

# Change the action on an existing rule
inkbox.mail_contact_rules.update(
    "sales.team@inkboxmail.com", rule_id, action="allow",
)
```

**TypeScript**

```typescript
// Pause a rule (keeps the slot reserved)
await inkbox.mailContactRules.update(
    "sales.team@inkboxmail.com",
    ruleId,
    { status: "paused" },
);

// Reactivate
await inkbox.mailContactRules.update(
    "sales.team@inkboxmail.com",
    ruleId,
    { status: "active" },
);

// Change the action on an existing rule
await inkbox.mailContactRules.update(
    "sales.team@inkboxmail.com",
    ruleId,
    { action: "allow" },
);
```

**CLI**

```bash
# Pause a rule
inkbox mailbox rules update <rule-id> --mailbox sales.team@inkboxmail.com --status paused

# Reactivate
inkbox mailbox rules update <rule-id> --mailbox sales.team@inkboxmail.com --status active
```

## Listing and auditing rules

List the rules on a single mailbox or phone number, or use the admin-only `list_all` methods to pull every rule in the organization — handy for compliance reviews or answering "is this sender blocked anywhere".

**Python**

```python
# Rules on one mailbox
rules = inkbox.mail_contact_rules.list("sales.team@inkboxmail.com", action="block")

# Org-wide mail rules (admin-only)
everything = inkbox.mail_contact_rules.list_all(action="block")
for r in everything:
    print(r.mailbox_id, r.match_type, r.match_target)

# Rules on one phone number
phone_rules = inkbox.phone_contact_rules.list(phone_number.id)

# Org-wide phone rules (admin-only)
all_phone = inkbox.phone_contact_rules.list_all(action="block")
```

**TypeScript**

```typescript
// Rules on one mailbox
const rules = await inkbox.mailContactRules.list("sales.team@inkboxmail.com", {
    action: "block",
});

// Org-wide mail rules (admin-only)
const everything = await inkbox.mailContactRules.listAll({ action: "block" });
for (const r of everything) {
    console.log(r.mailboxId, r.matchType, r.matchTarget);
}

// Rules on one phone number
const phoneRules = await inkbox.phoneContactRules.list(phoneNumber.id);

// Org-wide phone rules (admin-only)
const allPhone = await inkbox.phoneContactRules.listAll({ action: "block" });
```

**CLI**

```bash
# Rules on one mailbox
inkbox mailbox rules list --mailbox sales.team@inkboxmail.com --action block

# Rules on one phone number
inkbox number rules list --number <phone-number-id>
```

## Related

- [Mailbox contact rules API](/docs/api/mail/contact-rules)
- [Phone contact rules API](/docs/api/phone/contact-rules)
- [Mailboxes API](/docs/api/mail/mailboxes) — where `filter_mode` lives for mail
- [Phone numbers API](/docs/api/phone/numbers) — where `filter_mode` lives for phone