Skip to main content
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 increases. See Sending account management.

​
Authentication

Authenticate using an API key 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; root keys use smx_root_.

​
Permissions

EndpointRequired permission
POST /api/v1/emails/sendemail.send
POST /api/v1/emails/send/batchemail.send
GET /api/v1/openapi.jsonNone (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 or mailbox key 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 only. Use Content-Type: application/json.

​
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.