Replace mailbox sender filters

curl --request PUT \
  --url https://app.sendmux.ai/api/v1/mailboxes/{public_id}/filters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rules": [
    {
      "pattern": "partner.com",
      "note": "billing webhooks"
    }
  ]
}
'

{
  "ok": true,
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "data": {
    "rules": [
      {
        "pattern": "partner.com",
        "note": "billing webhooks"
      }
    ]
  }
}

Mailboxes

Replace mailbox sender filters

Atomically replaces the sender-filter mode and rule set for a mailbox. The entire rule set is swapped in a single operation — there is no intermediate state where the mailbox has a partial ruleset. A maximum of 1000 rules per request is enforced.

For optimistic concurrency, send If-Match: <etag> using the ETag from a prior GET. A mismatched If-Match returns 409 conflict (the server’s ETag is echoed back so you can decide whether to re-fetch). Responses carry the new ETag so chained edits can pipeline without a re-GET.

PUT

/

mailboxes

/

{public_id}

/

filters

Replace mailbox sender filters

curl --request PUT \
  --url https://app.sendmux.ai/api/v1/mailboxes/{public_id}/filters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rules": [
    {
      "pattern": "partner.com",
      "note": "billing webhooks"
    }
  ]
}
'

{
  "ok": true,
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "data": {
    "rules": [
      {
        "pattern": "partner.com",
        "note": "billing webhooks"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Sendmux API key. Use a root API key for Management API routes, or a mailbox credential for Mailbox API routes. Obtain keys from the dashboard under API Keys.

Headers

If-Match

string

Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs.

Path Parameters

public_id

string

required

Mailbox public ID

Body

application/json

mode

enum<string>

required

Available options:

off,

allowlist,

denylist

rules

object[]

required

Replacement rule set. Maximum 1000 rules per request. An empty array is valid (no rules).

Maximum array length: 1000

Hide child attributes

rules.type

enum<string>

required

Rule type

Available options:

allow,

deny

rules.pattern

string

required

Email address or bare domain name. Validated against RFC 5321/1035 regexes. The *@domain wildcard spelling is accepted and normalised to the bare domain (matching is by exact address or sender domain).

Example:

"partner.com"

rules.note

string | null

Free-form caption for the rule (≤255 chars). UI-only metadata — never consulted at match time. null when absent.

Maximum string length: 255

Example:

"billing webhooks"

Response

Updated filter state

ok

enum<boolean>

required

Available options:

true

meta

object

required

Hide child attributes

meta.request_id

string

required

Example:

"req_clxxxxxxxxxxxxxxxxxxxxxxxxx"

data

object

required

Hide child attributes

data.mode

enum<string>

required

Active filtering mode. off disables filtering (all senders accepted). allowlist only accepts senders matching a rule. denylist blocks senders matching a rule.

Available options:

off,

allowlist,

denylist

data.rules

object[]

required

Current rules, sorted by pattern ascending

Hide child attributes

data.rules.type

enum<string>

required

Rule type

Available options:

allow,

deny

data.rules.pattern

string

required

Email address or bare domain name. Validated against RFC 5321/1035 regexes. The *@domain wildcard spelling is accepted and normalised to the bare domain (matching is by exact address or sender domain).

Example:

"partner.com"

data.rules.note

string | null

Free-form caption for the rule (≤255 chars). UI-only metadata — never consulted at match time. null when absent.

Maximum string length: 255

Example:

"billing webhooks"

Get mailbox sender filters

Create a mailbox API key