Introduction

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. High-volume provider-routed sending stays in the Sending API.

Base URL

All Mailbox API requests should be made to:

https://app.sendmux.ai/api/v1

Authentication

Authenticate with a mailbox credential, REST OAuth access token, or agent access token from Sendmux. Pass it as a Bearer token in the Authorization header.

curl https://app.sendmux.ai/api/v1/mailbox/me \
  -H "Authorization: Bearer smx_mbx_your_key_here"

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. Agent access tokens use the smx_agent_ prefix and are limited by their granted scopes. Root API keys are rejected on Mailbox API endpoints. OAuth access tokens are for HTTP requests; they are not SMTP or IMAP passwords.

Current endpoints

Use GET /mailbox/connection to test an integration connection without checking storage or selecting a mailbox. GET /mailbox/me keeps its existing mailbox details and storage-usage behaviour.

Endpoint	Purpose
`GET /mailbox/connection`	Test authentication without selecting or reading a mailbox.
`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.
`PATCH /mailbox/identity`	Update the mailbox’s sender name and signatures.
`GET /mailbox/identities`	List sender identities available to the mailbox.
`GET /mailbox/messages`	List messages with filters, sorting, and cursor pagination.
`POST /mailbox/messages:batch-get`	Read exact message IDs with optional raw or clean body output.
`POST /mailbox/messages:batch-update`	Update allowed flags for multiple messages.
`POST /mailbox/messages:batch-delete`	Move or permanently delete multiple messages.
`GET /mailbox/messages/count`	Count messages matching filters without returning rows.
`GET /mailbox/messages/query-changes`	Read filtered message-list index changes since a prior state.
`GET /mailbox/messages/search-snippets`	Return subject and preview snippets for text searches.
`GET /mailbox/messages/{message_id}`	Read a message, including bodies and attachment metadata.
`GET /mailbox/messages/{message_id}/body`	Read raw body text, HTML, or both without cleaning.
`GET /mailbox/messages/{message_id}/content`	Read clean message content with body-cleaning controls.
`PATCH /mailbox/messages/{message_id}`	Update mutable message flags; `If-Match` adds stale-edit checks.
`DELETE /mailbox/messages/{message_id}`	Move or delete a message; `If-Match` adds stale-delete checks.
`POST /mailbox/attachments:upload`	Upload an attachment for a later send request.
`POST /mailbox/attachment-uploads`	Create a short-lived URL for a later attachment upload.
`GET /mailbox/messages/{message_id}/attachments/{attachment_id}`	Download an attachment.
`POST /mailbox/messages/send`	Send from the authenticated mailbox.
`GET /mailbox/threads`	List conversation threads with filters and cursor pagination.
`GET /mailbox/threads/{thread_id}`	Read thread metadata, message IDs, participants, and state.
`GET /mailbox/threads/{thread_id}/messages`	List message summaries for one thread.
`GET /mailbox/threads/{thread_id}/content`	Read clean message content for one thread with cursor pagination.
`GET /mailbox/folders`	List folders.
`POST /mailbox/folders`	Create a folder.
`GET /mailbox/folders/changes`	Read folder object changes since a prior folder state.
`GET /mailbox/folders/query-changes`	Read folder-list index changes since a prior query state.
`GET /mailbox/folders/{folder_id}`	Read one folder.
`PATCH /mailbox/folders/{folder_id}`	Update a folder; `If-Match` adds stale-edit checks.
`DELETE /mailbox/folders/{folder_id}`	Delete an empty custom folder; `If-Match` adds stale-delete checks.
`GET /mailbox/submissions`	List send submissions with filters and cursor pagination.
`GET /mailbox/submissions/changes`	Read submission object changes since a prior state.
`GET /mailbox/submissions/{submission_id}`	Read one send submission.
`GET /mailbox/quotas`	List mailbox quota usage and limits.
`GET /mailbox/quotas/changes`	Read quota object changes since a prior quota state.
`GET /mailbox/usage`	Read a compact usage view derived from quota records.
`GET /mailbox/changes`	Read message changes, or a typed resource state map.
`GET /mailbox/events`	Stream mailbox events with Server-Sent Events.

Import the Mailbox API Postman collection when you want ready-made requests.

Response format

The Mailbox API uses the same envelope as the Management API.

Success

{
  "ok": true,
  "data": {
    "id": "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
    "email": "agent@example.com"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Error

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "Mailbox not found.",
    "doc_url": "https://sendmux.ai/docs/api/errors#not_found",
    "retryable": false
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Every response includes an X-Request-Id header matching meta.request_id. Include that value when contacting support.

Rate limiting

Mailbox API keys are rate-limited to 1800 requests per minute. Rate limit headers are included on responses:

X-RateLimit-Limit: 1800
X-RateLimit-Remaining: 1794
X-RateLimit-Reset: 1679313700

When the limit is exceeded, the API returns 429 rate_limit_exceeded with a Retry-After header.

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

Mailbox API endpoints are included in the app API specification:

https://app.sendmux.ai/api/v1/openapi.json

Overview

Mailboxes

Session and identity

Messages

Attachments

Threads

Folders

Submissions

Usage

Sync

Base URL

Authentication

Current endpoints

Response format

Success

Error

Rate limiting

Conventions

OpenAPI specification

​Base URL

​Authentication

​Current endpoints

​Response format

​Success

​Error

​Rate limiting

​Conventions

​OpenAPI specification

Base URL

Authentication

Current endpoints

Response format

Success

Error

Rate limiting

Conventions

OpenAPI specification