From c75443c3251bcfeb7bf61589da429c522da1b9ae Mon Sep 17 00:00:00 2001 From: Roshan Jonnalagadda Date: Mon, 12 Oct 2026 16:06:19 +1300 Subject: [PATCH 1/4] docs: sync mailbox sender-choice contract --- docs.json | 1 + openapi-app.json | 259 ++++++++++++++++++ .../sendmux-mailbox.postman_collection.json | 197 +++++++++++++ 3 files changed, 457 insertions(+) diff --git a/docs.json b/docs.json index a04fd56..dbe69c1 100644 --- a/docs.json +++ b/docs.json @@ -344,6 +344,7 @@ "pages": [ "GET /mailbox/me", "GET /mailbox/session", + "GET /mailbox/sender-choices", "GET /mailbox/identity", "PATCH /mailbox/identity", "GET /mailbox/identities" diff --git a/openapi-app.json b/openapi-app.json index 19029f4..335c29b 100644 --- a/openapi-app.json +++ b/openapi-app.json @@ -5513,6 +5513,100 @@ ], "unevaluatedProperties": false }, + "MailboxSenderChoices": { + "additionalProperties": false, + "properties": { + "from": { + "additionalProperties": false, + "description": "Permitted exact From addresses and verified domains. Domains allow any localpart on that exact domain.", + "properties": { + "addresses": { + "items": { + "format": "email", + "maxLength": 254, + "type": "string" + }, + "maxItems": 1702, + "type": "array" + }, + "domains": { + "items": { + "maxLength": 253, + "type": "string" + }, + "maxItems": 100, + "type": "array" + } + }, + "required": [ + "addresses", + "domains" + ], + "type": "object" + }, + "origin_address": { + "description": "Originating inbox address; authorisation and billing remain attached to this inbox.", + "format": "email", + "type": "string" + }, + "reply_to": { + "additionalProperties": false, + "description": "Permitted exact Reply-To addresses and domains. The originating inbox is the default when permitted.", + "properties": { + "addresses": { + "items": { + "format": "email", + "maxLength": 254, + "type": "string" + }, + "maxItems": 1702, + "type": "array" + }, + "domains": { + "items": { + "maxLength": 253, + "type": "string" + }, + "maxItems": 100, + "type": "array" + } + }, + "required": [ + "addresses", + "domains" + ], + "type": "object" + } + }, + "required": [ + "origin_address", + "from", + "reply_to" + ], + "type": "object" + }, + "MailboxSenderChoicesResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "properties": { + "data": { + "$ref": "#/components/schemas/MailboxSenderChoices" + }, + "meta": { + "$ref": "#/components/schemas/ResponseMeta" + } + }, + "required": [ + "data" + ], + "type": "object" + } + ], + "unevaluatedProperties": false + }, "MailboxSendPolicy": { "additionalProperties": false, "properties": { @@ -6198,6 +6292,12 @@ "changes_limit_max": { "type": "integer" }, + "draft_schedule_days_max": { + "enum": [ + 30 + ], + "type": "integer" + }, "inline_attachment_bytes_max": { "type": "integer" }, @@ -6218,6 +6318,7 @@ } }, "required": [ + "draft_schedule_days_max", "list_limit_max", "changes_limit_max", "batch_ids_max", @@ -18061,6 +18162,164 @@ ] } }, + "/mailbox/sender-choices": { + "get": { + "description": "Intersects current team, inbox and credential policies with provider restrictions and selected delivery groups. Subdomains require separate authorisation. Sending checks these permissions again before submission.", + "operationId": "mailboxGetSenderChoices", + "parameters": [ + { + "description": "Restrict choices to these delivery groups.", + "in": "query", + "name": "delivery_group_id", + "required": false, + "schema": { + "description": "Restrict choices to these delivery groups.", + "items": { + "maxLength": 128, + "minLength": 1, + "type": "string" + }, + "maxItems": 50, + "type": "array" + } + }, + { + "description": "Return 304 when this ETag still matches.", + "in": "header", + "name": "If-None-Match", + "required": false, + "schema": { + "description": "Return 304 when this ETag still matches.", + "type": "string" + } + }, + { + "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.", + "in": "query", + "name": "mailbox_id", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MailboxSenderChoicesResponse" + } + } + }, + "description": "Current permitted choices.", + "headers": { + "ETag": { + "description": "Current choices version.", + "schema": { + "type": "string" + } + } + } + }, + "304": { + "description": "Choices are unchanged.", + "headers": { + "ETag": { + "description": "Current choices version.", + "schema": { + "type": "string" + } + } + } + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + }, + "description": "Request failed." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + }, + "description": "Request failed." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + }, + "description": "Request failed." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + }, + "description": "Request failed." + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + }, + "description": "Request failed." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + }, + "description": "Request failed." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + }, + "description": "Request failed." + } + }, + "security": [ + { + "bearerAuth": [] + }, + { + "oauth2": [ + "email.send" + ] + } + ], + "summary": "Get permitted sender choices", + "tags": [ + "Mailbox API" + ] + } + }, "/mailbox/session": { "get": { "description": "Returns mailbox API capabilities, resource state tokens, limits, and disabled feature flags for the authenticated mailbox.", diff --git a/postman/sendmux-mailbox.postman_collection.json b/postman/sendmux-mailbox.postman_collection.json index 766f003..cec7d4f 100644 --- a/postman/sendmux-mailbox.postman_collection.json +++ b/postman/sendmux-mailbox.postman_collection.json @@ -6200,6 +6200,203 @@ } ] }, + { + "event": [], + "name": "Get permitted sender choices", + "protocolProfileBehavior": { + "disableBodyPruning": true + }, + "request": { + "description": { + "content": "Intersects current team, inbox and credential policies with provider restrictions and selected delivery groups. Subdomains require separate authorisation. Sending checks these permissions again before submission.", + "type": "text/plain" + }, + "header": [ + { + "description": "Return 304 when this ETag still matches.", + "disabled": true, + "key": "If-None-Match", + "value": "" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "method": "GET", + "name": "Get permitted sender choices", + "url": { + "host": [ + "{{mailbox_base_url}}" + ], + "path": [ + "mailbox", + "sender-choices" + ], + "query": [ + { + "description": "Restrict choices to these delivery groups.", + "disabled": true, + "key": "delivery_group_id", + "value": "" + }, + { + "description": "Restrict choices to these delivery groups.", + "disabled": true, + "key": "delivery_group_id", + "value": "" + }, + { + "description": "Mailbox public ID to target when the credential grants access to more than one mailbox. Omit when the credential is scoped to exactly one mailbox.", + "disabled": true, + "key": "mailbox_id", + "value": "" + } + ], + "variable": [] + } + }, + "response": [ + { + "_postman_previewlanguage": "json", + "body": "", + "code": 200, + "cookie": [], + "header": [ + { + "description": "Current choices version.", + "disabled": true, + "key": "ETag", + "value": "string" + }, + { + "key": "Content-Type", + "value": "application/json" + } + ], + "name": "Current permitted choices.", + "status": "OK" + }, + { + "_postman_previewlanguage": "text", + "body": "", + "code": 304, + "cookie": [], + "header": [ + { + "description": "Current choices version.", + "disabled": true, + "key": "ETag", + "value": "string" + }, + { + "key": "Content-Type", + "value": "text/plain" + } + ], + "name": "Choices are unchanged.", + "status": "Not Modified" + }, + { + "_postman_previewlanguage": "json", + "body": "", + "code": 400, + "cookie": [], + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "name": "Request failed.", + "status": "Bad Request" + }, + { + "_postman_previewlanguage": "json", + "body": "", + "code": 401, + "cookie": [], + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "name": "Request failed.", + "status": "Unauthorized" + }, + { + "_postman_previewlanguage": "json", + "body": "", + "code": 403, + "cookie": [], + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "name": "Request failed.", + "status": "Forbidden" + }, + { + "_postman_previewlanguage": "json", + "body": "", + "code": 404, + "cookie": [], + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "name": "Request failed.", + "status": "Not Found" + }, + { + "_postman_previewlanguage": "json", + "body": "", + "code": 429, + "cookie": [], + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "name": "Request failed.", + "status": "Too Many Requests" + }, + { + "_postman_previewlanguage": "json", + "body": "", + "code": 500, + "cookie": [], + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "name": "Request failed.", + "status": "Internal Server Error" + }, + { + "_postman_previewlanguage": "json", + "body": "", + "code": 503, + "cookie": [], + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "name": "Request failed.", + "status": "Service Unavailable" + } + ] + }, { "event": [], "name": "Get mailbox API session", From 7ba16cceddf773b2242c97369f35d6b1e44e9a3b Mon Sep 17 00:00:00 2001 From: Roshan Jonnalagadda Date: Mon, 12 Oct 2026 17:36:44 +1300 Subject: [PATCH 2/4] docs: document reserved mailbox custom headers --- developer-tools/mailbox-api/saved-drafts.mdx | 2 ++ openapi-app.json | 8 ++++---- sending/http.mdx | 2 ++ 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/developer-tools/mailbox-api/saved-drafts.mdx b/developer-tools/mailbox-api/saved-drafts.mdx index 9279f84..01eb1d1 100644 --- a/developer-tools/mailbox-api/saved-drafts.mdx +++ b/developer-tools/mailbox-api/saved-drafts.mdx @@ -27,6 +27,8 @@ All draft requests require `mailbox.read`. Creating, editing and deleting also r Pass the revision you last read as `expected_revision`. A `409` means another edit won: read the draft again and review the newer content before retrying. Omitted fields keep their saved values. + Mailbox draft writes reject `X-SES-TENANT`, `X-SES-CONFIGURATION-SET` and `X-SES-MESSAGE-TAGS`, regardless of letter case. Older drafts containing these headers remain readable. To clear saved custom headers, include `"custom_headers": {}` in an update. + ```bash curl -X PATCH https://app.sendmux.ai/api/v1/mailbox/drafts/draft_123 \ -H "Authorization: Bearer $SENDMUX_API_KEY" \ diff --git a/openapi-app.json b/openapi-app.json index 335c29b..692c778 100644 --- a/openapi-app.json +++ b/openapi-app.json @@ -533,7 +533,7 @@ "additionalProperties": { "type": "string" }, - "description": "Custom X- headers preserved with this revision.", + "description": "Custom X-* headers. Writes reject X-SES-TENANT, X-SES-CONFIGURATION-SET and X-SES-MESSAGE-TAGS case-insensitively. On updates, omit this field to preserve saved headers, or pass {} to clear them.", "type": "object" }, "from": { @@ -3432,7 +3432,7 @@ "additionalProperties": { "type": "string" }, - "description": "Custom X- headers preserved with this revision.", + "description": "Custom X-* headers preserved with this revision. Older drafts containing reserved headers remain readable.", "type": "object" }, "failure_code": { @@ -8703,7 +8703,7 @@ "additionalProperties": { "type": "string" }, - "description": "Custom headers to include.", + "description": "Custom X-* headers to include. Mailbox writes reject X-SES-TENANT, X-SES-CONFIGURATION-SET and X-SES-MESSAGE-TAGS case-insensitively.", "type": "object" }, "from": { @@ -9374,7 +9374,7 @@ "additionalProperties": { "type": "string" }, - "description": "Custom X- headers preserved with this revision.", + "description": "Custom X-* headers. Writes reject X-SES-TENANT, X-SES-CONFIGURATION-SET and X-SES-MESSAGE-TAGS case-insensitively. On updates, omit this field to preserve saved headers, or pass {} to clear them.", "type": "object" }, "expected_revision": { diff --git a/sending/http.mdx b/sending/http.mdx index 6823b3b..e556a7c 100644 --- a/sending/http.mdx +++ b/sending/http.mdx @@ -99,6 +99,8 @@ Use the dedicated field for HTTP requests. `X-Sendmux-Delivery-Group` is reserve Use [template variables](/sending/template-variables) in the subject or body to insert values from the selected sending account. +For mailbox draft custom-header restrictions and clearing saved headers, see [Save, edit and send mailbox drafts](/developer-tools/mailbox-api/saved-drafts). + See the [Sending API reference](/sending-api/introduction) for the full schema. ## Error handling From 2f2551763600879043e805d096e787bd471f1c7e Mon Sep 17 00:00:00 2001 From: Roshan Jonnalagadda Date: Mon, 12 Oct 2026 21:30:40 +1300 Subject: [PATCH 3/4] docs: correct unsupported sending-account Card icons --- domains/index.mdx | 2 +- integrations/email-marketing/mailwizz.mdx | 2 +- monitoring/deliverability.mdx | 2 +- sending/accounts/delivery-groups.mdx | 2 +- sending/accounts/google-microsoft.mdx | 2 +- sending/accounts/http-provider.mdx | 2 +- sending/http.mdx | 2 +- sending/template-variables.mdx | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/domains/index.mdx b/domains/index.mdx index 4457039..e557470 100644 --- a/domains/index.mdx +++ b/domains/index.mdx @@ -134,7 +134,7 @@ Use the Management API when you want to create, list, upgrade, verify, or delete Review inbound controls for sending & receiving domains. - + Connect providers for outbound sending. diff --git a/integrations/email-marketing/mailwizz.mdx b/integrations/email-marketing/mailwizz.mdx index fe66ab3..917da3e 100644 --- a/integrations/email-marketing/mailwizz.mdx +++ b/integrations/email-marketing/mailwizz.mdx @@ -192,7 +192,7 @@ Start with a controlled campaign. Check delivery logs, bounces, complaints and r ## Related guides - + Add accounts and configure sender defaults, limits and routing. diff --git a/monitoring/deliverability.mdx b/monitoring/deliverability.mdx index 91e514f..507cdc1 100644 --- a/monitoring/deliverability.mdx +++ b/monitoring/deliverability.mdx @@ -59,7 +59,7 @@ Provider health shows the current monitored provider status, impact, and 24-hour > Filter logs and export message-level data. - + Review provider status, quotas, and routing. diff --git a/sending/accounts/delivery-groups.mdx b/sending/accounts/delivery-groups.mdx index 22154af..eacaed2 100644 --- a/sending/accounts/delivery-groups.mdx +++ b/sending/accounts/delivery-groups.mdx @@ -93,7 +93,7 @@ Deleting a group moves its providers to **No group**. Sendmux warns when API key ## Related guides - + Add providers and tune quotas, sender defaults, and weights. diff --git a/sending/accounts/google-microsoft.mdx b/sending/accounts/google-microsoft.mdx index 7522f81..b90570e 100644 --- a/sending/accounts/google-microsoft.mdx +++ b/sending/accounts/google-microsoft.mdx @@ -201,7 +201,7 @@ Importing creates the account records in one operation. Provider sign-in still h ## Related guides - + Import, configure, monitor, and route sending accounts. diff --git a/sending/accounts/http-provider.mdx b/sending/accounts/http-provider.mdx index 4e4e8ad..cd8b3b8 100644 --- a/sending/accounts/http-provider.mdx +++ b/sending/accounts/http-provider.mdx @@ -30,7 +30,7 @@ The disabled card is there so teams can see the planned provider category. There ## Related guides - + Add currently supported sending providers. diff --git a/sending/http.mdx b/sending/http.mdx index e556a7c..ce375ff 100644 --- a/sending/http.mdx +++ b/sending/http.mdx @@ -131,7 +131,7 @@ On Free, accepted and in-flight recipients share a limit of 50 per UTC day. When Make send retries safe with `Idempotency-Key`. - + Connect providers and control routing before you send. diff --git a/sending/template-variables.mdx b/sending/template-variables.mdx index c49cdad..50ced57 100644 --- a/sending/template-variables.mdx +++ b/sending/template-variables.mdx @@ -117,7 +117,7 @@ Omitting `variables` from a PATCH preserves the existing map. Supplying it repla Restrict a message to providers in selected groups. - + Configure the providers that supply template values. From 78af8694e16c2ee830d8ee6de2762f0d86e88ebf Mon Sep 17 00:00:00 2001 From: Roshan Jonnalagadda Date: Mon, 12 Oct 2026 21:50:59 +1300 Subject: [PATCH 4/4] docs: correct remaining unsupported Card icon names --- account/api-keys.mdx | 2 +- account/team-limits.mdx | 2 +- developer-tools/mailbox-api/sync.mdx | 2 +- developer-tools/postman.mdx | 2 +- domains/index.mdx | 2 +- getting-started/quickstart.mdx | 2 +- integrations/email-marketing/mailwizz.mdx | 2 +- monitoring/dashboard-logs.mdx | 2 +- monitoring/deliverability.mdx | 2 +- sending/idempotency.mdx | 4 ++-- sending/smtp.mdx | 2 +- 11 files changed, 12 insertions(+), 12 deletions(-) diff --git a/account/api-keys.mdx b/account/api-keys.mdx index ebced76..a3637c2 100644 --- a/account/api-keys.mdx +++ b/account/api-keys.mdx @@ -138,7 +138,7 @@ Mailbox keys also stop working while their mailbox is suspended, and work again Create mailbox keys and per-integration passwords. - + Handle authentication, permission, and rate-limit errors. diff --git a/account/team-limits.mdx b/account/team-limits.mdx index d952426..ef96c23 100644 --- a/account/team-limits.mdx +++ b/account/team-limits.mdx @@ -85,7 +85,7 @@ Pro does not have a Sendmux-wide outgoing volume cap. Managed sending limits, co Create, rotate, and revoke scoped keys. - + Handle `limit_exceeded` responses in API clients. diff --git a/developer-tools/mailbox-api/sync.mdx b/developer-tools/mailbox-api/sync.mdx index dc9ef7f..2f7137e 100644 --- a/developer-tools/mailbox-api/sync.mdx +++ b/developer-tools/mailbox-api/sync.mdx @@ -172,5 +172,5 @@ Supported `types` values are `messages`, `folders`, `threads`, `submissions`, - + diff --git a/developer-tools/postman.mdx b/developer-tools/postman.mdx index 89fa950..f86303f 100644 --- a/developer-tools/postman.mdx +++ b/developer-tools/postman.mdx @@ -90,7 +90,7 @@ Re-import the same URL when you want the latest requests. The collection files u Read authentication, permissions, response formats, and rate limits. diff --git a/domains/index.mdx b/domains/index.mdx index e557470..e2a33d4 100644 --- a/domains/index.mdx +++ b/domains/index.mdx @@ -131,7 +131,7 @@ Use the Management API when you want to create, list, upgrade, verify, or delete Create addresses on verified sending & receiving domains. - + Review inbound controls for sending & receiving domains. diff --git a/getting-started/quickstart.mdx b/getting-started/quickstart.mdx index 0126847..40aa763 100644 --- a/getting-started/quickstart.mdx +++ b/getting-started/quickstart.mdx @@ -90,7 +90,7 @@ This guide gets a new team to its first tracked email. Use the shared domain for Create scoped keys for sending, monitoring, and automation. - + Search, filter, refresh, and export delivery activity. diff --git a/integrations/email-marketing/mailwizz.mdx b/integrations/email-marketing/mailwizz.mdx index 917da3e..a37d93c 100644 --- a/integrations/email-marketing/mailwizz.mdx +++ b/integrations/email-marketing/mailwizz.mdx @@ -198,7 +198,7 @@ Start with a controlled campaign. Check delivery logs, bounces, complaints and r Keep selected sending accounts together for a chosen traffic stream. - + Review message status and investigate delivery activity. diff --git a/monitoring/dashboard-logs.mdx b/monitoring/dashboard-logs.mdx index 0c09ac0..bde5aff 100644 --- a/monitoring/dashboard-logs.mdx +++ b/monitoring/dashboard-logs.mdx @@ -75,7 +75,7 @@ Use the Management API to read email metrics, list logs, and fetch one log by ID Receive delivery and inbound events. - + Handle send failures in API clients. diff --git a/monitoring/deliverability.mdx b/monitoring/deliverability.mdx index 507cdc1..ba70b4a 100644 --- a/monitoring/deliverability.mdx +++ b/monitoring/deliverability.mdx @@ -54,7 +54,7 @@ Provider health shows the current monitored provider status, impact, and 24-hour Filter logs and export message-level data. diff --git a/sending/idempotency.mdx b/sending/idempotency.mdx index 348dcc9..ceb1719 100644 --- a/sending/idempotency.mdx +++ b/sending/idempotency.mdx @@ -65,10 +65,10 @@ Use the header on mutating endpoints such as sending email, creating domains, cr Use idempotency with single and batch sends. - + Handle conflicts from single and batch sends. - + Handle conflicts from management requests. diff --git a/sending/smtp.mdx b/sending/smtp.mdx index a59cb88..c4c6855 100644 --- a/sending/smtp.mdx +++ b/sending/smtp.mdx @@ -84,7 +84,7 @@ When no daily capacity remains, SMTP returns `550 5.7.1 Daily sending limit reac Create the credentials used as SMTP passwords. - + Search and export SMTP delivery results.