Sending by HTTP

Use the HTTP Sending API for new integrations, batch sending, and retry-safe requests.

Routing follows the credential you authenticate with. Use delivery_group to restrict an individual message to authorised delivery groups.

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

Prerequisites

A team with sending access.
A send-only key or mailbox key with email.send.
Enough team balance for the messages you send.
A verified sending-only or sending & receiving custom domain if you send through the managed account, unless you are testing with the shared domain. Sends through your own sending accounts do not need one, because each account already authenticates at its own provider.

Send one email

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@example.com", "name": "Your App" },
    "to": { "email": "user@example.com", "name": "Jane Doe" },
    "subject": "Welcome",
    "html_body": "<p>Thanks for signing up.</p>",
    "text_body": "Thanks for signing up."
  }'

A successful request returns 200 OK with a queued message_id.

Send a batch

Send up to 100 messages in one request. The response reports each message by its input index.

curl -X POST https://smtp.sendmux.ai/api/v1/emails/send/batch \
  -H "Authorization: Bearer smx_mbx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "from": { "email": "hello@example.com" },
        "to": { "email": "alice@example.com" },
        "subject": "Hello Alice",
        "html_body": "<p>Hi Alice.</p>"
      },
      {
        "from": { "email": "hello@example.com" },
        "to": { "email": "bob@example.com" },
        "subject": "Hello Bob",
        "html_body": "<p>Hi Bob.</p>"
      }
    ]
  }'

A batch can return 200 OK while some messages fail. Check data.summary.failed, then inspect every item in data.results by index. Queued items include a message_id; failed items include error details.

Useful options

Select delivery groups

Add delivery_group to a single-send body or to each message in messages for a batch. It accepts one public ID or a nonempty array of public IDs:

{ "delivery_group": ["dgrp_group_a", "dgrp_group_b"] }

Replace the example IDs with your groups’ public IDs. Use at most 50 groups; surrounding whitespace is trimmed and repeated IDs are deduplicated. Each batch message can select different groups, within the credential’s scope. Use the dedicated field for HTTP requests. X-Sendmux-Delivery-Group is reserved and cannot be supplied through custom_headers. See Delivery groups for scope rules and shared-domain overrides.

Other options

Option	Use it for
`cc`, `bcc`	Add recipients, up to 50 recipients total across To, CC, and BCC.
`reply_to`	Direct replies to a different address.
`return_path`	Set the envelope sender for bounce handling.
`custom_headers`	Add custom `X-*` headers to the outgoing message.
`attachments`	Attach uploaded `attachment_id` refs, or tiny inline base64 content.
`Idempotency-Key`	Safely retry a request without sending twice.

Use template variables in the subject or body to insert values from the selected sending account. See the Sending API reference for the full schema.

Error handling

Check the ok field. If it is false, read error.code, error.message, and meta.request_id.

const data = await response.json();

if (!data.ok) {
  console.error(data.error.code, data.error.message, data.meta.request_id);
}

Use Sending API errors for retry and support guidance. On Free, accepted and in-flight recipients share a limit of 50 per UTC day. When a new request would cross it, Sendmux returns 429 daily_limit_exceeded before queueing that message. A queued message that reaches a full UTC day waits for the next reset. Wait for the Retry-After period or upgrade to Pro.

SMTP sending

Use SMTP when an existing tool only supports SMTP delivery.

Attachments

Add files to HTTP send requests.

Idempotency

Make send retries safe with Idempotency-Key.

Sending accounts

Connect providers and control routing before you send.

Getting started

Developer tools

AI integrations

Sending

Receiving

Domains

Monitoring

Webhooks

Use cases

Integrations

Account and billing

Sending by HTTP

Prerequisites

Send one email

Send a batch

Useful options

Select delivery groups

Other options

Error handling

SMTP sending

Attachments

Idempotency

Sending accounts

​Prerequisites

​Send one email

​Send a batch

​Useful options

​Select delivery groups

​Other options

​Error handling

​Related guides

SMTP sending

Attachments

Idempotency

Sending accounts

Prerequisites

Send one email

Send a batch

Useful options

Select delivery groups

Other options

Error handling

Related guides