Introduction

The Sendmux Sending API lets you send emails programmatically through the managed Amazon SES account or your own configured providers. It supports single and batch sending, attachments, idempotency keys, and structured per-message results.

Managed Amazon SES is for transactional email only. Use your own provider for marketing, newsletters, or bulk promotional sends.

Base URL

All Sending API requests should be made to:

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

This is a different base URL from the Management API (app.sendmux.ai).

Use the Management API to manage the accounts that the Sending API can use: list accounts, add custom SMTP accounts, activate or deactivate accounts, test SMTP connections, read usage, and request limit reviews when eligible. See Sending account management.

Authentication

Authenticate using an API key or REST OAuth access token with the email.send permission. Pass it as a Bearer token in the Authorization header.

curl -X POST https://smtp.sendmux.ai/api/v1/emails/send \
  -H "Authorization: Bearer smx_mbx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "hello@yourdomain.com", "name": "Your App" },
    "to": { "email": "user@example.com" },
    "subject": "Welcome!",
    "html_body": "<h1>Welcome to our platform</h1>"
  }'

API keys are scoped to a team. Create and manage keys under Settings > API Keys in the Sendmux app. Keys used for sending require the email.send permission. Send-only keys and mailbox keys use the smx_mbx_ prefix; owner-approved agent tokens use smx_agent_; root keys use smx_root_.

Durable agent read tokens use the smx_agent_ prefix, but they do not include email.send. After the owner accepts the invitation and approves sending, the agent can exchange one for a one-hour Sending-resource smx_agent_ token through agent access.

Permissions

Use GET /me to test an integration connection without sending email. It requires email.send and returns the team, credential, permissions, and connection label.

Endpoint	Required permission
`POST /api/v1/emails/send`	`email.send`
`POST /api/v1/emails/send/batch`	`email.send`
`POST /api/v1/emails/attachments`	`email.send`
`GET /api/v1/emails/attachments/{attachment_id}`	`email.send`
`POST /api/v1/emails/attachment-uploads`	`email.send`
`PUT /api/v1/emails/attachment-uploads/{upload_id}`	Upload token
`GET /api/v1/openapi.json`	None (public)

Account-management endpoints live in the Management API and use root API keys with provider.* permissions.

Response format

All responses use the same JSON envelope as the Management API.

Success

{
  "ok": true,
  "data": {
    "message_id": "eml_abc123def456ghi789jkl012",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Error

{
  "ok": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Your team's balance is too low to send this email.",
    "doc_url": "https://sendmux.ai/docs/sending-api/errors#insufficient_credits",
    "retryable": false
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

The Sending API uses the same envelope as the Management API: code, message, param, doc_url, retryable, accumulated errors[], X-Request-Id, and Retry-After. See the Sending API error reference for email delivery codes.

Rate limits

Each send-only key, mailbox key, or owner-approved agent token used on the Sending API is rate-limited to 1,800 requests per 60 seconds. A batch send counts as 1 request, regardless of how many messages it contains. Management API keys are limited separately to 600 requests per 60 seconds. See the Management API introduction. Every response carries the current rate-limit state plus a request identifier:

X-RateLimit-Limit: 1800
X-RateLimit-Remaining: 1794
X-RateLimit-Reset: 1679313700
X-Request-Id: req_clxxxxxxxxxxxxxxxxxxxxxxxxx

X-Request-Id matches meta.request_id in the JSON envelope. Include it when contacting support. When the limit is exceeded, the API returns a 429 status with a Retry-After header indicating how many seconds to wait before retrying.

Conditional requests

Single-resource GET responses return a weak ETag. Send it back in an If-None-Match header on the next request; if the resource is unchanged the API responds 304 Not Modified with no body, saving bandwidth. This is supported across the Sending API and the Management API mailbox, domain, webhook, and log resources.

Conventions

snake_case fields in all JSON request and response bodies
UTC ISO 8601 timestamps in RFC 3339 format: 2026-03-19T10:30:00Z
Public IDs only. Private numeric IDs are never exposed.
Cache-Control: no-store on all authenticated responses (the OpenAPI spec endpoint uses public, max-age=3600)
JSON endpoints use Content-Type: application/json.
Binary attachment upload endpoints use Content-Type for the file MIME type and require the exact Content-Length for the raw byte body.

OpenAPI specification

The full OpenAPI 3.1 specification is available at:

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

You can also import the Sending API Postman collection by URL.

Overview

Emails

Attachments

Base URL

Authentication

Permissions

Response format

Success

Error

Rate limits

Conditional requests

Conventions

OpenAPI specification

​Base URL

​Authentication

​Permissions

​Response format

​Success

​Error

​Rate limits

​Conditional requests

​Conventions

​OpenAPI specification

Base URL

Authentication

Permissions

Response format

Success

Error

Rate limits

Conditional requests

Conventions

OpenAPI specification