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 HTTP API is the recommended way to send emails from your application. It supports single and batch sending with structured JSON requests.

​
Prerequisites

1

Active delivery provider

A Sendmux account with at least one active delivery provider configured.
2

API key with sending permission

An API key with the email.send permission. Create one under Settings > API Keys.
3

Sufficient balance

Check your team’s balance under Billing — sends are debited per message.

​
Send a single email

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

​
Response

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

​
Send a batch of emails

Send up to 100 emails in a single request. The API uses a partial success model — individual message failures don’t fail the entire batch. 
curl -X POST https://smtp.sendmux.ai/api/v1/emails/send/batch \
  -H "Authorization: Bearer smx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "from": { "email": "hello@yourdomain.com" },
        "to": { "email": "alice@example.com" },
        "subject": "Hello Alice",
        "html_body": "<p>Hi Alice!</p>"
      },
      {
        "from": { "email": "hello@yourdomain.com" },
        "to": { "email": "bob@example.com" },
        "subject": "Hello Bob",
        "html_body": "<p>Hi Bob!</p>"
      }
    ]
  }'

​
Batch response

{
  "ok": true,
  "data": {
    "results": [
      { "index": 0, "message_id": "eml_abc123def456ghi789jkl012", "status": "queued" },
      { "index": 1, "message_id": "eml_mno345pqr678stu901vwx234", "status": "queued" }
    ],
    "summary": { "total": 2, "queued": 2, "failed": 0 }
  },
  "meta": { "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx" }
}

​
Optional fields

The full request schema — every optional field, its type, and constraints — is rendered from the live OpenAPI spec on the POST /emails/send page in the Sending API reference. A few fields warrant their own guides:
  • Attachments — base64-encoded files. See the Attachments guide.
  • Idempotency — pass an Idempotency-Key HTTP header (not a body field) to make retries safe. See the Idempotency guide.

​
Error handling

Always check the ok field in the response: 
const data = await response.json();

if (!data.ok) {
  console.error(`Error ${data.error.code}: ${data.error.message}`);
  // Handle specific error codes
  if (data.error.code === "insufficient_credits") {
    // Top up balance
  }
}
See the full error reference for all error codes.