Sendmux · roshanjonah · Jun 11, 2026 · Jun 11, 2026
diff --git a/changelog.mdx b/changelog.mdx
@@ -1,9 +1,20 @@
 ---
 title: "Product updates"
 description: "New features, improvements, and fixes across the Sendmux platform."
 rss: true
 ---
 
+<Update label="11 June 2026" tags={["Improvements"]} rss={{ title: "Hosted MCP can grant selected mailbox sets" }}>
+  ## Hosted MCP
+
+Hosted Product MCP can now grant one or more selected mailboxes in the same connected app. Agents can search the granted mailbox set, target a mailbox for each mailbox action, and remain blocked from any mailbox that was not authorised.
+
+  ## Mailbox API
+
+Connected-app Mailbox API requests now support `mailbox_id` targeting. Use `GET /mailbox/mailboxes` to list or search the mailboxes available to the token before making a mailbox-specific request.
+
+</Update>
+
 <Update label="11 June 2026" tags={["Bug fixes"]} rss={{ title: "MCP connected apps clean up repeated authorisations" }}>
   ## Bug fixes
 
@@ -18,7 +29,7 @@

 Local MCP setups can now use the same product-line selection for one, several, or all product lines.

 Local all-product-line MCP setups can use separate keys for each product line, so teams can keep least-privilege key boundaries while still giving an agent the full curated toolset.

 Hosted Product MCP Sending tools now keep the same permission, sending-scope, and rate-limit checks as direct Sending API calls before each send request is accepted.

@@ -28,7 +39,7 @@

 Re-authorising an existing connected app now replaces its previous product-line grant, so removed product lines disappear from that app instead of leaving stale access behind.

 ## SDKs and CLI

 SDK and CLI surfaces now account for every documented operation and expose the supported options and filters.

@@ -54,7 +65,7 @@
 <Update label="7 June 2026" tags={["Bug fixes"]} rss={{ title: "Inbox quota sync is more reliable" }}>
  ## Bug fixes

 - Inbox quota sync now tells clients when quota data should be refetched instead of returning an invalid sync error.

 </Update>

@@ -78,20 +89,20 @@
 <Update label="4 June 2026" tags={["New features"]} rss={{ title: "Hosted MCP access is ready for agents" }}>
  ## Hosted MCP

 Teams can now connect supported agent tools to Sendmux through a hosted MCP endpoint, authorise access in the browser, and grant only the inbox and account permissions they choose.

 ## Improvements

 - The authorisation flow now has clear sign-in, consent, success, denied, and error states.
 - Headless clients can use scoped access tokens with the same permission checks as browser-based connections.
 - Agent tools now follow the same Sendmux role and key permissions used by the API, so unavailable actions stay hidden and blocked.

 </Update>

 <Update label="2 June 2026" tags={["Improvements","Bug fixes"]} rss={{ title: "Inbox credentials are more reliable" }}>
  ## Inboxes

 Inbox credentials now use provider-issued secrets while preserving Sendmux key IDs, improving compatibility with the managed mailbox platform.

 ## Improvements

@@ -107,8 +118,8 @@
 <Update label="2 June 2026" tags={["Bug fixes"]} rss={{ title: "Shared mailbox creation is more reliable" }}>
  ## Bug fixes

 - Creating a mailbox on the shared Sendmux domain now checks the shared-domain setup before provisioning the mailbox, so generated addresses no longer fail when required domain records are missing.
 - Domain creation and deletion now consistently protect the shared Sendmux domain while still letting teams delete the mailboxes they created.
 - Sign-up legal links now use shorter labels so the agreement line fits better on narrow screens.

 </Update>
@@ -139,7 +150,7 @@

 ## Bug fixes

 - Draft autosave now backs off while a message is sending, reducing duplicate saves and avoidable rate-limit warnings.
 - Email buttons now render with a consistent background across email clients.
 - Deliverability alerts now count bounce rate and complaint rate separately when both need attention.

@@ -170,7 +181,7 @@
 ## Improvements

 - The health strip now fills completed hours and shows the selected hour's sent, received, and failed counts directly in the summary.
 - Activity chart tooltips now match the dashboard style and stay compact while you inspect daily sending and receiving totals.
 - Domain status now uses the latest saved verification details so SPF, DKIM, and DMARC signals can be shown independently after checks run.

 ## Bug fixes
@@ -192,7 +203,7 @@

 The team overview now shows a clearer health summary with recent sending, receiving, webhook, billing, domain, API key, and capacity signals together in one place.

 Activity charts now use cached rollups so dashboard refreshes stay fast for busy teams.

 ## Improvements

@@ -225,14 +236,14 @@
 <Update label="28 May 2026" tags={["Improvements","Bug fixes"]} rss={{ title: "Inbox layout, autosave, and log tables are easier to use" }}>
  ## Improvements

 - The dashboard sidebar now narrows on smaller screens and keeps **Documentation**, **Feedback**, balance, and **Top up** inside the scrollable menu.
 - The **Inboxes** page now gives more room to the open message on narrower desktop screens while keeping the folder menu and conversation list usable.

 ## Bug fixes

 - Sending and receiving log tables now fit typical browser widths without unnecessary horizontal scrolling.
 - Long message IDs in log tables now show a short readable prefix, so columns stay aligned while the full value remains available.
 - Drafts now autosave once the basic message details are present, and the **Drafts** count updates after the first save.
 - Inbox folder counts now only appear where they are meaningful: unread **Inbox**, all **Drafts**, and all **Spam**.
 - Mailbox filters now hide inactive or deleted mailbox addresses.
 - Incoming log senders now show the message sender instead of a message identifier.
@@ -254,7 +265,7 @@
 ## Improvements

 - Webhook event selection now includes search, making it faster to choose the right events when setting up or editing a webhook.
 - The dashboard setup checklist now adapts better on small screens and keeps long task lists within the viewport.

 ## Bug fixes

@@ -338,7 +349,7 @@
 <Update label="25 May 2026" tags={["New features","Improvements","Bug fixes"]} rss={{ title: "Team setup, sending account management, mailbox suspension, and attachment limits are improved" }}>
  ## Team setup

 Team creation now walks you through the setup details we need upfront: your team name, website, industry, how you found Sendmux, preferences, and what you're building. If you want help, you can book a 15-minute consultation without leaving setup.

 Signed-in browser agents can create teams after login too, using retry-safe requests so automated onboarding doesn't double-create a team when a request is retried.

@@ -387,9 +398,9 @@

 See [Billing](/guides/billing) and [Mailboxes](/guides/mailboxes).

 ## Realtime mailbox events

 The Mailbox API now includes `GET /mailbox/events`, a Server-Sent Events stream for `message.received` and `message.received.spam`. Use it for agents, CLIs, and SDKs that need live mailbox updates without polling.

 The stream supports heartbeats, bounded connection lifetimes, and resume with `Last-Event-ID` or `last_event_id`. If the replay window is no longer available, the stream tells the client to sync before reconnecting.

@@ -404,7 +415,7 @@
 - Limit usage now appears at the bottom-right of the relevant dashboard pages, so it stays available without crowding the page header.
 - The API key limit now covers active root and mailbox-class credentials, including send-only and mailbox credentials.
 - The team limits guide now clarifies default limits, increase requests, and that email volume is not capped beyond existing sending limits.
 - Webhooks and mailbox realtime events use the same public `message.received` event names for inbound mailbox activity.

 ## Bug fixes

@@ -421,7 +432,7 @@

 - Mailbox lists now show `Name` before `Email`, with clearer column labels.
 - Long domain, mailbox, and webhook headings now stay on one line with cleaner truncation.
 - Long webhook endpoint URLs are clipped in lists and can be inspected from the hover tooltip.
 - Team menus now include a direct **Invite members** action.

 ## Bug fixes
@@ -509,7 +520,7 @@
 - Consistent success and error response formats.
 - A request ID on every response for support correlation.
 - Cursor pagination on all list endpoints.
 - ETags and conditional requests (`If-None-Match` / `If-Match`) to save bandwidth and prevent lost updates.
 - [Idempotency keys](/guides/idempotency) so create requests can be retried safely.
 - Rate-limit responses now report the exact number of seconds until your limit resets.

@@ -571,10 +582,10 @@

 </Update>

 <Update label="20 March 2026" tags={["New features"]} rss={{ title: "Sendmux is here — dashboard, sending accounts, dollar-based billing, the Sending API, and a read-only Management API" }}>
  ## Sendmux is here

 Welcome to Sendmux. The initial release includes:

 - **Dashboard** — an at-a-glance overview with sending charts and a searchable, filterable delivery-log viewer with CSV export.
 - **Sending accounts** — connect accounts over SMTP or with Gmail and Microsoft 365 (including GCC High, DoD, and China clouds), organise them into groups, bulk-test connections, and import in bulk from CSV. See [Sending accounts](/guides/sending-accounts).

diff --git a/docs.json b/docs.json
@@ -198,6 +198,7 @@
           {
             "group": "Mailbox",
             "pages": [
+              "GET /mailbox/mailboxes",
               "GET /mailbox/me",
               "GET /mailbox/session",
               "GET /mailbox/identity",

diff --git a/guides/api-keys.mdx b/guides/api-keys.mdx
@@ -1,6 +1,6 @@
 ---
 title: "API keys"
 description: "Create, scope, rotate, and revoke Sendmux API keys."
 keywords:
  [
    "API keys",
@@ -21,7 +21,7 @@

 | Credential class | Created by | Secret lifetime | Where to manage it |
 | --- | --- | --- | --- |
 | **Manual API key** | A team member creates a key in Sendmux. | Long-lived until you rotate or revoke it. | **API Keys** with the **Manual keys** filter. |
 | **Connected app** | You authorise an app through OAuth, such as Product MCP. | 15-minute access tokens with rotating refresh tokens. | **API Keys** with the **Connected apps** filter. |

 Revoking a manual API key stops that key. Disconnecting a connected app stops that app refreshing access and using its existing connection.
@@ -43,9 +43,9 @@
 
 ## Connected apps
 
-Connected apps let tools such as Product MCP act with the product lines you authorise. During authorisation, you can choose Management, Mailbox, Sending, or a combination. Sendmux then issues a short-lived access token for the app and a refresh token that rotates when used.
+Connected apps let tools such as Product MCP act with the product lines you authorise. During authorisation, you can choose Management, Mailbox, Sending, or a combination. If you choose Mailbox, you also choose the mailbox set the app can use. Sendmux then issues a short-lived access token for the app and a refresh token that rotates when used.
 
-Connected apps do not create `smx_root_` or `smx_mbx_` secrets. They are listed separately from manual API keys so you can see which app is connected, which product lines it can use, who authorised it, when it was last used, and how many requests it has made.
+Connected apps do not create `smx_root_` or `smx_mbx_` secrets. They are listed separately from manual API keys so you can see which app is connected, which product lines it can use, which mailbox set is selected, who authorised it, when it was last used, and how many requests it has made.
 
 To manage connected apps:
 
@@ -61,7 +61,7 @@
   </Step>
 </Steps>
 
-Re-authorising the same app updates the existing connection instead of creating unused manual API keys. If you choose fewer product lines during re-authorisation, tools from the removed product lines stop being available to that app.
+Re-authorising the same app updates the existing connection instead of creating unused manual API keys. If you choose fewer product lines or mailboxes during re-authorisation, removed tools and mailbox targets stop being available to that app.
 
 ## Create a key
 
@@ -72,7 +72,7 @@
    through all providers, selected providers, or delivery groups.
  </Step>
  <Step title="Store the secret">
    Copy the generated `smx_root_` or `smx_mbx_` value. Sendmux will not show it again.
  </Step>
 </Steps>

@@ -98,7 +98,7 @@
 3. Deploy the new secret to every system that uses it.
 4. Revoke the old key once all callers have moved.

 If your team is already at the API key limit, Sendmux requires the old key to be revoked during rotation.

 ## Revoke a key


diff --git a/guides/mcp.mdx b/guides/mcp.mdx
@@ -1,17 +1,17 @@
 ---
 title: "AI integrations"
 description: "Connect AI tools to Sendmux documentation and product tools."
 keywords: ["MCP", "Model Context Protocol", "Claude", "Cursor", "VS Code", "AI agents"]
 ---

 Sendmux has two MCP connections:

 - **Documentation MCP** lets AI tools search Sendmux guides and API references.
 - **Product MCP** lets an AI agent use the Sendmux product lines you choose: Management, Mailbox, Sending, or any combination of them.

 ## Documentation MCP

 Use this when you want an AI tool to answer questions from the Sendmux docs.

 | Setting | Value |
 | --- | --- |
@@ -81,12 +81,12 @@
 | Product line | What the agent can do | Credential authority |
 | --- | --- | --- |
 | Management | Manage domains, mailboxes, sending accounts, webhooks, logs, metrics, and billing data. | Team-level access |
-| Mailbox | Read, search, organise, thread, and send from one mailbox. | Mailbox access |
+| Mailbox | Read, search, organise, thread, and send from selected mailboxes. | Selected mailbox access |
 | Sending | Send outbound email without mailbox reading tools. | Sending access |
 
 <Info>
   Choosing more product lines never grants more authority than your team role,
-  selected mailbox, and consent allow. Tools for product lines you did not
+  selected mailbox set, and consent allow. Tools for product lines you did not
   authorise are not shown to the agent.
 </Info>
 
@@ -112,14 +112,20 @@
     Select Management, Mailbox, Sending, or any combination. Choose all three
     when the agent should see every curated Sendmux tool.
   </Step>
+  <Step title="Choose mailboxes">
+    If you select Mailbox, choose one or more mailboxes the agent can use. Use
+    search or select all when your team has many mailboxes.
+  </Step>
   <Step title="Authorise">
     Review the requested access and select **Authorise**.
   </Step>
 </Steps>
 
 Connected apps use short-lived access tokens that last 15 minutes. Refresh tokens rotate on use and can last up to 30 days unless the connection is disconnected or the grant expires. The connection does not create a manual `smx_root_` or `smx_mbx_` API key.
 
-Re-authorising the same hosted connection replaces the previous product-line selection for that app. Product lines you remove during re-authorisation disappear from the agent's tool list.
+When more than one mailbox is granted, agents can call `mailbox_list_granted_mailboxes` to search the granted set and pass `mailbox_id` to mailbox tools. If only one mailbox is granted, mailbox tools use it by default.
+
+Re-authorising the same hosted connection replaces the previous product-line and mailbox selections for that app. Product lines or mailboxes you remove during re-authorisation disappear from the agent's tool list or allowed mailbox targets.
 
 Hosted Product MCP requests keep the same permission, sending-scope, and rate-limit checks as direct Sendmux API requests before each request is accepted. For example, adding Sending tools to an agent does not let it send from mailboxes, sending accounts, or account groups outside the access you granted.
 
@@ -167,9 +173,11 @@
 
 Use separate keys for separate local product lines when that is how your team grants least-privilege access. For example, a local all-three setup can use one management key plus separate mailbox and sending keys.
 
+Local MCP with a manual mailbox key acts as that one mailbox. Hosted Product MCP can grant a mailbox set and target each mailbox by `mailbox_id`.
+
 ## Tool coverage
 
 <Info>
  MCP exposes a curated agent toolset, not every API endpoint. Use the SDKs,
  CLI, or API reference when you need full endpoint coverage.
 </Info>
diff --git a/mailbox-api/introduction.mdx b/mailbox-api/introduction.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Introduction"
-description: "Mailbox-scoped API endpoints for a single Sendmux mailbox."
+description: "Mailbox-scoped API endpoints for Sendmux mailbox credentials and connected apps."
 keywords:
   [
     "mailbox API",
@@ -14,7 +14,7 @@
   ]
 ---
 
-The Sendmux Mailbox API is for mailbox-scoped credentials. Use it when a client should act only as the mailbox tied to its API key, not manage team-wide resources.
+The Sendmux Mailbox API is for mailbox-scoped access. Use it when a client should act as a mailbox, or as one mailbox from a connected-app mailbox set, without managing team-wide resources.
 
 Team-wide mailbox provisioning stays in the [Management API](/api/introduction). High-volume provider-routed sending stays in the [Sending API](/sending-api/introduction).
 
@@ -28,19 +28,20 @@
 
 ## Authentication
 
-Authenticate with a mailbox credential from the Sendmux app. Pass it as a Bearer token in the `Authorization` header.
+Authenticate with a mailbox credential or connected-app access token from the Sendmux app. Pass it as a Bearer token in the `Authorization` header.
 
 ```bash
 curl https://app.sendmux.ai/api/v1/mailbox/me \
   -H "Authorization: Bearer smx_mbx_your_key_here"
 ```
 
-Mailbox credentials are scoped to one mailbox. Root API keys are rejected on Mailbox API endpoints. The same credential is also accepted as the mailbox password for SMTP submission and IMAP retrieval.
+Manual mailbox credentials are scoped to one mailbox. The same credential is also accepted as the mailbox password for SMTP submission and IMAP retrieval. Connected-app tokens can be granted one or more mailboxes, and each mailbox request is limited to that granted set. Root API keys are rejected on Mailbox API endpoints.
 
 ## Current endpoints
 
 | Endpoint                                                         | Purpose                                                           |
 | ---------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `GET /mailbox/mailboxes`                                         | List and search mailboxes granted to the bearer token.            |
 | `GET /mailbox/me`                                                | Return the mailbox associated with the bearer token.              |
 | `GET /mailbox/session`                                           | Return supported capabilities, limits, and current state tokens.  |
 | `GET /mailbox/identity`                                          | Return the mailbox's default sender identity and signatures.      |
@@ -83,10 +84,28 @@
 
 Import the [Mailbox API Postman collection](/guides/postman-collection#choose-a-collection) when you want ready-made requests.
 
+## Mailbox targeting for connected apps
+
+Manual mailbox credentials always target their single mailbox. Omit `mailbox_id` when you use a manual `smx_mbx_` credential.
+
+Connected-app tokens can grant a set of mailboxes. Use `GET /mailbox/mailboxes` to list or search the granted set, then pass the selected mailbox's `id` as `mailbox_id` on Mailbox API requests.
+
+```bash
+curl "https://app.sendmux.ai/api/v1/mailbox/mailboxes?q=support" \
+  -H "Authorization: Bearer connected_app_access_token"
+```
+
+```bash
+curl "https://app.sendmux.ai/api/v1/mailbox/messages?mailbox_id=mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx&limit=10" \
+  -H "Authorization: Bearer connected_app_access_token"
+```
+
+If a connected app has exactly one granted mailbox, Mailbox API requests use that mailbox by default. If several mailboxes are granted and you omit `mailbox_id`, Sendmux returns `400 missing_parameter`. If you pass a mailbox outside the grant, Sendmux returns `403 insufficient_permissions`.
+
 ## Capability discovery
 
 Use `GET /mailbox/session` before planning a mailbox workflow. It returns the
-mailbox tied to the credential, supported Mailbox API features, current state
+selected mailbox, supported Mailbox API features, current state
 tokens, request limits, and gated features. A gated feature is intentionally
 unavailable through the Mailbox API.
 
@@ -402,7 +421,7 @@
 | `from`           | Search the From header.                                        |
 | `to`             | Search the To header.                                          |
 | `cc`             | Search the Cc header.                                          |
 | `bcc`            | Search the Bcc header.                                         |
 | `subject`        | Search subject text.                                           |
 | `body`           | Search body text.                                              |
 | `header_name`    | Match messages with a specific header.                         |
@@ -810,7 +829,7 @@
 ### Event stream

 `GET /mailbox/events` streams mailbox events as Server-Sent Events. Use it for
 agents, CLIs, MCP servers, and SDKs that need to react when inbound mail arrives.
 Use [webhooks](/guides/webhooks-setup) instead when a backend service should
 receive signed event POSTs without keeping a live connection open.

@@ -1016,12 +1035,12 @@

 ## Conventions

 - **snake_case** fields in JSON request and response bodies
 - **UTC ISO 8601 timestamps** in RFC 3339 format: `2026-03-19T10:30:00Z`
 - **Opaque IDs only** for mailbox, message, folder, and attachment resources
 - **`Cache-Control: no-store`** on authenticated responses
 - **Weak `ETag`** headers on single-resource GETs where supported
 - **Header-based idempotency** for retriable POST requests where supported

 ## OpenAPI specification