Sender rules

Sender rules control who an inbox may receive from and who it may send to. OpenMail evaluates them server-side, before delivery and before a send goes out. An agent cannot bypass them: a scoped key cannot read or change policy at all.

The model

A policy has two halves: inbound (who may write to you) and outbound (who you may write to). Each half is set independently. Policy lives at three scopes:

Scope	Applies to
Account	Every inbox you own
Pod	Every inbox in that pod
Inbox	One inbox

Each direction at each scope has a mode:

Mode	Behavior
`none`	No filtering. Block rules still apply.
`allowlist`	Only listed senders or recipients are permitted.
`inherit`	Defer to the parent scope. Not valid at the account scope, which is the root.

Inheritance

The two halves inherit differently:

Modes override. Resolution walks inbox → pod → account and stops at the first scope with a mode other than inherit. If nothing is set anywhere, the mode is none.
Rules accumulate. The effective rule set is the union of every rule at every scope in the chain. There is no override and no exception list.

A pod-level block cannot be cancelled by an inbox-level allow. A tighter scope can narrow what it inherits, but never loosen it.

How a decision is made

For each address being evaluated:

Block rules apply first, at every scope in the chain, regardless of mode. A match denies. No mode lets a blocked address through.
In allowlist mode, the address must then match an allow rule from some scope in the chain. No match denies.
In none mode, anything not blocked is permitted.

An address matches a rule when the rule is:

an exact email address: agent@partner.com matches only that address; or
a whole domain: partner.com matches every address at partner.com.

Matching is case-insensitive and values are stored lowercased. The domain is taken from the last @ in the address, so a quoted local part cannot get a different domain past a block.

Empty allowlists fail closed

An allowlist with no allow rules denies everything.

One compatibility exception: policies created through the console carry a legacy flag under which an empty inbound allowlist accepts all mail, and the console shows a warning instead of locking you out. Outbound is fail-closed in every case. Policies created through PUT /v1/policy are fail-closed in both directions.

What is enforced, and where

Inbound

Checked against the sender’s From address when mail arrives. Denied mail is dropped before it is threaded or stored; it never reaches your inbox, fires no webhook or WebSocket event, and doesn’t count toward storage. The sender gets no bounce or notification. The drop shows up as an inbound_rejected event in History; there is no quarantine view.

Outbound

Checked in the send path that every surface goes through, so one enforcement point covers the REST API, the CLI, the SDK, the console compose box, replies, and forwards. Every address a send can reach is checked:

Field	Checked
`to`	Yes
`cc`	Yes, after the auto-CC merge, so a thread reply cannot add a recipient that skips the check
`replyTo`	Yes, otherwise a reply could be routed to an address outside the approved set
`bcc`	Not supported. See below.

One denied recipient rejects the whole send. There is no partial delivery, and a rejected send does not count against your rate limits.

// 403 Forbidden
{
  "error": "recipient_not_permitted",
  "recipient": "stranger@elsewhere.com",
  "message": "Sending to stranger@elsewhere.com is not permitted by this inbox's outbound recipient policy."
}

Bcc is not supported

OpenMail has no Bcc. A send carrying a bcc field is rejected rather than accepted with the field ignored. Accepting it would mean reporting success for a recipient that was never delivered to and never checked against your rules.

// 400 Bad Request
{
  "error": "unsupported_field",
  "field": "bcc",
  "message": "Bcc is not supported. Send to each recipient separately, or use 'cc' — every 'to', 'cc', and 'replyTo' address is checked against this inbox's outbound recipient policy."
}

Who can change policy

Surface	Credential	Who
Console (Allow/Block List)	Session	Account owner only. Members get read-only access.
`/v1/policy`	Account-wide API key	Any holder of an account-wide key

A pod- or inbox-scoped key, the kind an agent runs with, gets 403 on every policy endpoint, reads included. An agent cannot change the rules that apply to it, and cannot see them either.

// 403 Forbidden
{
  "error": "forbidden",
  "message": "This API key is scoped and cannot manage policy."
}

History

Every rule change, and every send or delivery that was refused, is recorded in your Allow/Block List history. Entries can’t be edited or deleted, not even over the API.

Action	Recorded when	`detail` contains
`rule_added`	A rule is created	`type`, `valueType`, `value`
`rule_removed`	A rule is deleted	`type`, `valueType`, `value`
`mode_changed`	A direction’s mode changes	`from`, `to`
`scope_deleted`	A pod or inbox is deleted, cascade-deleting its policy	`inboundMode`, `outboundMode`, `removedRules`
`send_rejected`	Outbound policy refuses a send	`rejectedRecipient`, `reason`, `matchedScope`
`inbound_rejected`	Inbound policy refuses delivery	`rejectedSender`, `reason`, `matchedScope`

Each event also carries its scope, the direction where one applies, and the console user who made the change. The two rejection actions have no actor; they are written by enforcement, not a person.

scope_deleted records the modes and rules removed when a pod or inbox is deleted, since deleting a scope also deletes its policy.
inbound_rejected is often the only trace of a refused delivery: the sender gets no bounce and the recipient never sees the message.

Rejection events are deduplicated to one entry per inbox and address per hour, so a retry loop against a blocked address cannot flood the history. Check it in the console under Allow/Block List → History, or over the API:

curl -H "Authorization: Bearer $OPENMAIL_API_KEY" \
  "https://api.openmail.sh/v1/policy/audit?action=send_rejected,inbound_rejected&since=2026-08-01T00:00:00Z"

API reference

All policy endpoints require an account-wide API key. Select the scope with ?podId= or ?inboxId=; neither means the account scope.

Method	Path	Purpose
`GET`	`/v1/policy`	Read a scope’s modes, own rules, and inherited rules
`PUT`	`/v1/policy`	Set modes and replace rules in one call, for provisioning
`PUT`	`/v1/policy/mode`	Set one direction’s mode
`POST`	`/v1/policy/rules`	Add one allow/block rule
`DELETE`	`/v1/policy/rules/:id`	Remove a rule
`GET`	`/v1/policy/audit`	Read the history

Set up rules in one call

PUT /v1/policy sets modes and replaces the scope’s own rules for any direction you include, so re-running it converges to the state you declared instead of accumulating rules. Omitted directions are left untouched; pass [] to clear a direction’s rules. The whole body is validated before anything is applied, so a bad outbound section cannot leave a half-applied inbound section behind.

curl -X PUT "https://api.openmail.sh/v1/policy?inboxId=$INBOX_ID" \
  -H "Authorization: Bearer $OPENMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound":  { "mode": "allowlist", "rules": [{ "type": "allow", "value": "partner.com" }] },
    "outbound": { "mode": "allowlist", "rules": [
      { "type": "allow", "value": "support@partner.com" },
      { "type": "allow", "value": "ops@partner.com" }
    ]}
  }'

Up to 500 rules per direction per call.

Read what is in force

GET /v1/policy returns the scope’s own modes and rules plus what it inherits, so you can see what actually applies without walking the chain yourself:

{
  "scope": "inbox",
  "rules": [],
  "inheritedRules": [],
  "modes": {
    "inbound":  { "mode": "inherit",   "inheritedMode": "allowlist", "inheritedSource": "account" },
    "outbound": { "mode": "allowlist", "inheritedMode": "none",      "inheritedSource": "default" }
  }
}

rules are set on this scope; inheritedRules come from the pod and account. An inherited rule can only be removed at the scope that owns it; deleting one from a child scope returns 403 inherited_rule.

History query parameters

Parameter	Notes
`action`	Comma-separated: `rule_added`, `rule_removed`, `mode_changed`, `scope_deleted`, `send_rejected`, `inbound_rejected`. An unknown name returns `400`.
`direction`	`inbound` or `outbound`
`podId` / `inboxId`	Events recorded at that scope, matched exactly. An inbox filter does not include the account-level changes it inherits.
`since` / `until`	ISO 8601. `since` inclusive, `until` exclusive. An unparseable value returns `400`.
`limit` / `offset`	Page size 1–100, default 50. The response includes an unpaginated `total`.

Worked example

One pod per customer tenant, one inbox per agent. The account blocks what nobody should reach, the pod narrows it to the tenant, the inbox narrows it to one contact.

# 1. Account floor: block a domain everywhere. No pod or inbox can undo this.
curl -X POST "https://api.openmail.sh/v1/policy/rules" \
  -H "Authorization: Bearer $OPENMAIL_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "block", "value": "known-bad.example", "direction": "outbound" }'

# 2. Pod: this tenant's agents may only email within the tenant's domain.
curl -X PUT "https://api.openmail.sh/v1/policy?podId=$POD_ID" \
  -H "Authorization: Bearer $OPENMAIL_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "inbound":  { "mode": "allowlist", "rules": [{ "type": "allow", "value": "tenant.com" }] },
    "outbound": { "mode": "allowlist", "rules": [{ "type": "allow", "value": "tenant.com" }] }
  }'

# 3. Inbox: this one agent talks to exactly one mailbox.
curl -X PUT "https://api.openmail.sh/v1/policy?inboxId=$INBOX_ID" \
  -H "Authorization: Bearer $OPENMAIL_API_KEY" -H "Content-Type: application/json" \
  -d '{ "outbound": { "mode": "allowlist", "rules": [{ "type": "allow", "value": "ap@tenant.com" }] } }'

# 4. Mint the agent's key. It can read and send from this inbox, and nothing else.
curl -X POST "https://api.openmail.sh/v1/inboxes/$INBOX_ID/api-keys" \
  -H "Authorization: Bearer $OPENMAIL_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "invoice-agent" }'

The agent’s key can send only from its inbox, only to ap@tenant.com, and never to known-bad.example. It cannot read the policy, change it, or mint a broader key. Every attempt to reach outside that set is refused synchronously and recorded.

Managing rules in the console

Go to Allow/Block List in the Dashboard. The account owner can:

Add email addresses or domains to the allow or block list, per direction
Switch each direction’s mode between none, allowlist, and inherit
Remove rules owned by the scope being viewed
Check the History tab to see what changed and what was refused

Members see the same page read-only.

Limits

Domain rules do not match subdomains. example.com covers bob@example.com but not bob@mail.example.com. Add each domain you want covered.
No wildcards or regular expressions. A rule is an exact address or an exact domain.
Rules are address-based only. There is no filtering on subject, body content, or attachment type.
Denied inbound mail is dropped silently. No bounce, no notification, no quarantine view. The drop is recorded as an inbound_rejected event in History.
A value cannot be in both allow and block for the same direction at the same scope. The API rejects this with 409, since block always wins and the allow would be dead. Across different scopes it is permitted, and block still wins.
No plan gating. Sender rules are available on every plan.

Sender rules work alongside suppressions. Suppressions automatically block addresses that have bounced or been reported as spam. Sender rules give you manual control on top of that.

Get started

Core concepts

WebSockets

Webhooks

Guides

Integrations

Best practices

Resources

Security & privacy

The model

Inheritance

How a decision is made

Empty allowlists fail closed

What is enforced, and where

Inbound

Outbound

Bcc is not supported

Who can change policy

History

API reference

Set up rules in one call

Read what is in force

History query parameters

Worked example

Managing rules in the console

Limits

​The model

​Inheritance

​How a decision is made

​Empty allowlists fail closed

​What is enforced, and where

​Inbound

​Outbound

​Bcc is not supported

​Who can change policy

​History

​API reference

​Set up rules in one call

​Read what is in force

​History query parameters

​Worked example

​Managing rules in the console

​Limits

The model

Inheritance

How a decision is made

Empty allowlists fail closed

What is enforced, and where

Inbound

Outbound

Bcc is not supported

Who can change policy

History

API reference

Set up rules in one call

Read what is in force

History query parameters

Worked example

Managing rules in the console

Limits