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"
}
]
}
'import requests
url = "https://app.sendmux.ai/api/v1/mailboxes/{public_id}/filters"
payload = { "rules": [
{
"pattern": "partner.com",
"note": "billing webhooks"
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({rules: [{pattern: 'partner.com', note: 'billing webhooks'}]})
};
fetch('https://app.sendmux.ai/api/v1/mailboxes/{public_id}/filters', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.sendmux.ai/api/v1/mailboxes/{public_id}/filters"
payload := strings.NewReader("{\n \"rules\": [\n {\n \"pattern\": \"partner.com\",\n \"note\": \"billing webhooks\"\n }\n ]\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": true,
"data": {
"rules": [
{
"pattern": "partner.com",
"note": "billing webhooks"
}
]
}
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}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.
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"
}
]
}
'import requests
url = "https://app.sendmux.ai/api/v1/mailboxes/{public_id}/filters"
payload = { "rules": [
{
"pattern": "partner.com",
"note": "billing webhooks"
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({rules: [{pattern: 'partner.com', note: 'billing webhooks'}]})
};
fetch('https://app.sendmux.ai/api/v1/mailboxes/{public_id}/filters', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.sendmux.ai/api/v1/mailboxes/{public_id}/filters"
payload := strings.NewReader("{\n \"rules\": [\n {\n \"pattern\": \"partner.com\",\n \"note\": \"billing webhooks\"\n }\n ]\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": true,
"data": {
"rules": [
{
"pattern": "partner.com",
"note": "billing webhooks"
}
]
}
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}{
"error": {
"code": "invalid_parameter",
"message": "<string>",
"retryable": false,
"doc_url": "<string>",
"errors": [
{
"code": "invalid_string",
"field": "recipient.email",
"message": "<string>"
}
],
"param": "<string>"
},
"meta": {
"request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"ok": false
}Authorizations
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
Weak ETag from a prior GET. Reject with 409 conflict when the server's current ETag differs.
Path Parameters
Mailbox public ID
Body
off, allowlist, denylist Replacement rule set. Maximum 1000 rules per request. An empty array is valid (no rules).
1000Hide child attributes
Hide child attributes
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).
"partner.com"
Rule type
allow, deny Free-form caption for the rule (≤255 chars). UI-only metadata — never consulted at match time. null when absent.
255"billing webhooks"
Response
Updated filter state
true Hide child attributes
Hide child attributes
Active filtering mode. off disables filtering (all senders accepted). allowlist only accepts senders matching a rule. denylist blocks senders matching a rule.
off, allowlist, denylist Current rules, sorted by pattern ascending
Hide child attributes
Hide child attributes
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).
"partner.com"
Rule type
allow, deny Free-form caption for the rule (≤255 chars). UI-only metadata — never consulted at match time. null when absent.
255"billing webhooks"
Was this page helpful?