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

# Send Transactional Email: POST /mail/send Reference

> Send transactional or marketing emails via HTTP POST. Supports HTML, plain text, CC, BCC, custom headers, attachments, and per-message reference IDs.

The `/mail/send` endpoint is the core of turboSMTP's HTTP API. Use it to send transactional receipts, password resets, marketing campaigns, or any other programmatic email from your application. You submit a JSON payload containing the sender, recipients, subject, and body content, and turboSMTP queues and delivers the message through its global relay infrastructure. This endpoint uses a dedicated sending host and requires Consumer Key / Secret headers with the HTTP API Sending permission enabled.

## Endpoint

```text Global endpoint theme={"system"}
POST https://api.turbo-smtp.com/api/v2/mail/send
```

For EU infrastructure, use:

```text EU endpoint theme={"system"}
POST https://api.eu.turbo-smtp.com/api/v2/mail/send
```

> [!WARNING]
>
> This endpoint requires `consumerKey` and `consumerSecret` request headers. An `Authorization` header is ignored and cannot replace the key pair. Your Consumer Secret is not your account login password. Create credentials at **Settings → Integrations → API Keys → Edit** in the [dashboard](https://dashboard.serversmtp.com).

## Request headers

| Header | Required | Description |
| - | - | - |
| `consumerKey` | Yes | Your Consumer Key (public identifier) |
| `consumerSecret` | Yes | Your Consumer Secret (credential) |
| `Content-Type` | Yes | Must be `application/json` |

## Request body parameters

**from** `string` *required*

The sender's email address, optionally with a display name: `Name <sender@example.com>`. Use a domain you have verified with turboSMTP.

**to** `string` *required*

One or more recipient email addresses, comma-separated (e.g. `alice@example.com, bob@example.com`).

**subject** `string`

The email subject line displayed in the recipient's inbox. The API specification sets a maximum of 700 characters.

**content** `string`

The plain-text body of the email. Recommended for maximum deliverability: include this alongside `html_content` whenever possible.

**html\_content** `string`

The HTML body of the email. Use alongside `content` to provide a plain-text fallback.

**cc** `string`

Comma-separated list of email addresses to CC on the message.

**bcc** `string`

Comma-separated list of email addresses to BCC. Recipients in this field are hidden from all other recipients.

**custom\_headers** `object`

A JSON object of additional SMTP headers to attach to the message. Example: `{"Reply-To": "support@example.com", "X-Mailer": "MyApp"}`.

**reference\_id** `string`

A custom identifier included in event webhook data when provided. Use a UUID to correlate sends with your application records.

**X-campaign-ID** `string`

A campaign identifier used to group messages. This is a top-level JSON body field with this exact capitalization, separate from `custom_headers`. Read it back through [analytics](/docs/api-reference/analytics.md) (`filter_by=x_campaign_id`). The `X-Campaign-Id` header on the delivered message is internal routing data, not this value.

**mime\_raw** `string`

Accepted by the request schema, but `/mail/send` does not use it. A request that carries only `mime_raw` is delivered with an empty body, and the raw message's headers and subject are discarded; when `content` or `html_content` is present, those are sent instead. To send a pre-built MIME message, use the [SMTP relay](/docs/sending/smtp-relay.md).

**attachments** `array`

An array of attachment objects. See the [Attachment object](#attachment-object) section below.

## Attachment object

Each item in the `attachments` array must be an object with the following fields:

**name** `string` *required*

The filename of the attachment as it will appear to the recipient, including extension (e.g. `invoice-2024.pdf`).

**type** `string` *required*

The MIME type of the file content (e.g. `application/pdf`, `image/png`, `image/gif`).

**content** `string` *required*

The Base64-encoded content of the file. Encode the raw binary of the file before including it here.

**content\_id** `string`

Optional bare identifier for an inline attachment, such as `logo`. For a sender at `example.com`, reference it in HTML as `cid:logo@example.com`. See [inline images](/docs/sending/attachments.md#inline-images).

## Example request

```bash Terminal theme={"system"}
curl -X POST 'https://api.turbo-smtp.com/api/v2/mail/send' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "hello@your-company.com",
    "to": "recipient@example.com",
    "subject": "Welcome!",
    "content": "Thanks for signing up.",
    "html_content": "<p>Thanks for <strong>signing up</strong>.</p>"
  }'
```

### Example with attachment

```bash Terminal theme={"system"}
curl -X POST 'https://api.turbo-smtp.com/api/v2/mail/send' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "billing@your-company.com",
    "to": "customer@example.com",
    "subject": "Your Invoice",
    "content": "Please find your invoice attached.",
    "html_content": "<p>Please find your invoice attached.</p>",
    "reference_id": "333fe3e9-05aa-4ead-85cf-de625b0222c6",
    "attachments": [
      {
        "name": "invoice-00123.pdf",
        "type": "application/pdf",
        "content": "BASE64_ENCODED_PDF_CONTENT"
      }
    ]
  }'
```

### Successful response

```json theme={"system"}
{
  "message": "OK",
  "mid": 1475205839938715648
}
```

## Response codes

| Code | Status | Description |
| - | - | - |
| `200` | OK | turboSMTP successfully received and queued your message. |
| `400` | Bad Request | The request body or parameters are malformed or missing required fields. |
| `401` | Unauthorized | Authentication failed: invalid, missing, or wrong type of credentials. |
| `500` | Server Unavailable | An unexpected error occurred on the turboSMTP server. |

## Error responses

Error formats vary by failure. Inspect the HTTP status and the returned `message`, `errors`, or `details` fields. A successful queue response does not confirm final delivery; use analytics or delivery webhooks for that.

> [accordion] Missing or invalid credentials
>
> ```json theme={"system"}
> {
>   "errorCode": 3,
>   "message": "Invalid authorization token",
>   "details": "No authorization key was specified for request: POST /api/mail/send"
> }
> ```

> [accordion] Invalid recipient address
>
> ```json theme={"system"}
> {
>   "message": "error",
>   "errors": [
>     ["'bad-email' 'to' email not valid"],
>     "missing recipients (to)"
>   ]
> }
> ```

> [accordion] Missing sender address
>
> ```json theme={"system"}
> {
>   "message": "error",
>   "errors": [
>     "missing or not valid sender email (from)"
>   ]
> }
> ```

> [accordion] Insufficient sending credits
>
> ```json theme={"system"}
> {
>   "message": "error",
>   "errors": {
>     "message": "error",
>     "errors": "nocredit"
>   }
> }
> ```

> [accordion] Deactivated account
>
> ```json theme={"system"}
> {
>   "error": 3,
>   "message": "Account for test@domain.com is inactive"
> }
> ```

> [!NOTE]
>
> Keep the total message size, including attachments and encoding overhead, under **24 MB**. This is not a 24 MB raw-file allowance. See [attachment limits](/docs/sending/attachments.md#attachment-limits).


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