Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sendmux.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Sendmux Management API gives you programmatic access to your email infrastructure: read providers, metrics, and delivery logs; manage domains, mailboxes, API keys, and webhook subscriptions; track billing balance and history. Use it to build monitoring dashboards, automate provisioning, and integrate Sendmux into your own back-office tooling.

​
Base URL

All API requests should be made to: 
https://app.sendmux.ai/api/v1

​
Authentication

Authenticate using an API key from the Sendmux app. Pass it as a Bearer token in the Authorization header. 
curl https://app.sendmux.ai/api/v1/providers \
  -H "Authorization: Bearer smx_root_your_key_here"
API keys are scoped to a team and carry specific permissions. Create and manage keys under Settings > API Keys in the Sendmux app.

​
Permissions

Each endpoint requires a specific permission. Keys with wildcard permissions (e.g. domain.*) satisfy any permission in that namespace, and the built-in root:full role includes every wildcard.
Endpoint groupRequired permission(s)
Providersprovider.read
Email metricsanalytics.read
Email logslogs.read
Billingbilling.read
Domainsdomain.read for reads; domain.create, domain.verify, domain.delete for the matching mutations.
Mailboxesmailbox.admin.read for reads; mailbox.admin.create for create; mailbox.admin.delete for delete; mailbox.admin.manage for update, filter management, and per-mailbox API-key management.
Webhookswebhook.read for reads; webhook.create, webhook.update, webhook.delete for the matching mutations; webhook.manage for rotate-secret and test.
Use the root:readonly role for monitoring integrations — it covers every *.read permission. root:webhook_admin is a narrower preset for keys that should only manage webhook subscriptions.

​
Response format

All responses use a consistent JSON envelope.

​
Success

{
  "ok": true,
  "data": { ... },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

​
Paginated success

List endpoints include a pagination object alongside data. 
{
  "ok": true,
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_cursor": "dlog_xxxxxxxx"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

​
Error

{
  "ok": false,
  "error": {
    "code": "invalid_parameter",
    "message": "The 'from_date' parameter must be a valid ISO 8601 date.",
    "param": "from_date",
    "doc_url": "https://docs.sendmux.ai/api-reference/errors#invalid_parameter",
    "retryable": false
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
The retryable flag distinguishes transient failures (back off and retry) from permanent ones (fix the request). See the errors reference for the full envelope shape, the accumulated errors[] array on validation failures, and the Retry-After header semantics for 429/503.

​
Errors

HTTP statusError codeDefault retryableDescription
400invalid_parameterfalseBad query parameter format or syntactic body validation failure.
400missing_parameterfalseRequired parameter missing.
401authentication_requiredfalseNo or invalid API key.
403insufficient_permissionsfalseKey lacks required permission.
404not_foundfalseResource does not exist or belongs to a different team.
409conflictfalseResource state forbids the operation (e.g. If-Match mismatch).
409idempotency_conflictfalseIdempotency-Key reused with a different body or while in-flight.
413payload_too_largefalseRequest body exceeds the server-side size limit.
422validation_errorfalseBody parsed but violates a semantic rule.
429rate_limit_exceededtrueRate limit hit. Retry-After header included.
500internal_errortrueUnexpected server error.
503service_unavailabletrueDownstream component briefly unavailable. May include Retry-After.

​
Rate limiting

Each API key is rate-limited to 600 requests per minute. Rate limit headers are included on every response: 
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1679313700
When the limit is exceeded, the API returns a 429 status with a Retry-After header.

​
Conventions

  • snake_case fields in all JSON responses
  • UTC ISO 8601 timestamps in RFC 3339 format: 2026-03-19T10:30:00Z
  • Public IDs only — internal database IDs are never exposed
  • Cache-Control: no-store on all responses
  • JSON only — Content-Type: application/json

​
OpenAPI specification

The full OpenAPI 3.1 specification is available at: 
https://app.sendmux.ai/api/v1/openapi.json
Use it with any OpenAPI-compatible tool to generate client libraries or explore the API.