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

# Sending by HTTP

> Send single or batch email requests through the Qubrics Sending API.

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

> [!NOTE]
>
> Routing follows the credential you authenticate with. Use `delivery_group` to
> restrict an individual message to authorised delivery groups.

> [!WARNING]
>
> 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

```bash theme={null}
curl -X POST https://smtp.qubrics.com/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.

```bash theme={null}
curl -X POST https://smtp.qubrics.com/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:

```json theme={null}
{ "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-Qubrics-Delivery-Group` is reserved and cannot be supplied through `custom_headers`. See [Delivery groups](https://sendmux.ai/docs/sending/accounts/delivery-groups.md#restrict-one-message) 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](https://sendmux.ai/docs/sending/template-variables.md) in the subject or body to insert values from the selected sending account.

For mailbox draft custom-header restrictions and clearing saved headers, see [Save, edit and send mailbox drafts](https://sendmux.ai/docs/developer-tools/mailbox-api/saved-drafts.md).

See the [Sending API reference](https://sendmux.ai/docs/sending-api/introduction.md) for the full schema.

## Error handling

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

```js theme={null}
const data = await response.json();

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

Use [Sending API errors](https://sendmux.ai/docs/sending-api/errors.md) 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, Qubrics 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.

## Related guides

> [card] [SMTP sending](https://sendmux.ai/docs/sending/smtp.md)
>
> Use SMTP when an existing tool only supports SMTP delivery.

> [card] [Attachments](https://sendmux.ai/docs/sending/attachments.md)
>
> Add files to HTTP send requests.

> [card] [Idempotency](https://sendmux.ai/docs/sending/idempotency.md)
>
> Make send retries safe with `Idempotency-Key`.

> [card] [Sending accounts](https://sendmux.ai/docs/sending/accounts)
>
> Connect providers and control routing before you send.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.