> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Send emails programmatically via the Sendmux Sending API.

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.

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

## Base URL

All Sending API requests should be made to:

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

<Note>
  This is a different base URL from the [Management
  API](/api/introduction) (`app.sendmux.ai`).
</Note>

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](/api/introduction#sending-account-management).

## Authentication

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

```bash theme={null}
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_`.

<Note>
  Pre-claim agent tokens use the `smx_agent_` prefix, but they do not include
  `email.send`. After the owner approves sending, the agent can request a
  Sending-resource `smx_agent_` token through
  [agent access](/guides/agent-access).
</Note>

### Permissions

| Endpoint                         | Required permission |
| -------------------------------- | ------------------- |
| `POST /api/v1/emails/send`       | `email.send`        |
| `POST /api/v1/emails/send/batch` | `email.send`        |
| `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

```json theme={null}
{
  "ok": true,
  "data": {
    "message_id": "eml_abc123def456ghi789jkl012",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

### Error

```json theme={null}
{
  "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](/api/introduction): `code`, `message`, `param`, `doc_url`, `retryable`, accumulated `errors[]`, `X-Request-Id`, and `Retry-After`. See the [Sending API error reference](/sending-api/errors) 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](/api/introduction#rate-limits).

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](/api/introduction#conditional-requests) 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](/guides/postman-collection#choose-a-collection) by URL.