> ## 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 via the turboSMTP REST API

> Make HTTP POST requests to send emails programmatically with turboSMTP's v2 REST API. Supports HTML, plain text, CC, BCC, custom headers, and attachments.

The turboSMTP REST API lets you send email over HTTPS without an SMTP client library. Make a single HTTP POST request with a JSON body to dispatch transactional messages, notifications, or bulk campaigns from any language or platform that can speak HTTP. The API supports HTML and plain-text bodies, multiple recipients, CC and BCC, custom headers, per-message tracking IDs for webhook correlation, and attachments within the 24 MB total message limit, including encoding overhead.

## Endpoints

turboSMTP provides two send endpoints. Choose based on your data-residency requirements.

| Region | Endpoint |
| - | - |
| **Global** | `https://api.turbo-smtp.com/api/v2/mail/send` |
| **EU** | `https://api.eu.turbo-smtp.com/api/v2/mail/send` |

> [!TIP]
>
> turboSMTP is an Italian company with European sending infrastructure. Use `api.eu.turbo-smtp.com` for the EU sending route. Review [data residency](/docs/api-reference/base-urls.md#gdpr-and-data-residency) for compliance considerations.

> [!WARNING]
>
> `POST /mail/send` requires `consumerKey` and `consumerSecret` headers with **HTTP API Sending** enabled. An `Authorization` header is ignored and cannot authenticate the request by itself. See [API keys](/docs/get-started/api-keys.md) to create credentials.

## Request headers

Send these three headers with every `/mail/send` request.

| Header | Value | Required |
| - | - | - |
| `consumerKey` | Your Consumer Key | ✅ Yes |
| `consumerSecret` | Your Consumer Secret | ✅ Yes |
| `Content-Type` | `application/json` | ✅ Yes |

## Request body

The request body must be a JSON object. The `from` and `to` fields are required; all other fields are optional.

**from** `string` *required*

The sender's email address. Use a verified sender domain so your messages can authenticate as your domain. You can include a display name: `"Your Company <hello@your-company.com>"`.

**to** `string` *required*

One or more recipient email addresses. Separate multiple addresses with commas. Example: `"alice@example.com,bob@example.com"`

**subject** `string`

The subject line of the email. The API specification sets a maximum of 700 characters.

**content** `string`

The plain-text body of the email. Include this field to ensure compatibility with email clients that do not render HTML.

**html\_content** `string`

The HTML body of the email. You can provide both `content` and `html_content` in the same request; email clients that support HTML will render `html_content` and fall back to `content`.

**cc** `string`

One or more CC (carbon copy) email addresses, comma-separated.

**bcc** `string`

One or more BCC (blind carbon copy) email addresses, comma-separated. BCC recipients are hidden from all other recipients.

**custom\_headers** `object`

Additional SMTP headers to include in the message, expressed as a JSON object. Example: `{"Reply-To": "support@example.com", "X-Mailer": "MyApp/1.0"}`

**reference\_id** `string`

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

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

A top-level campaign identifier used to group messages. Use this exact capitalization. Filter by it in analytics; the `X-Campaign-Id` header on the delivered message is internal and does not carry this value.

**attachments** `array`

An array of attachment objects. Each object must include `name` (filename), `type` (MIME type), and `content` (Base64-encoded file data). Add optional `content_id` for [inline images](/docs/sending/attachments.md#inline-images). The total size of the email including all attachments must be under 24 MB. See [Attachments](/docs/sending/attachments.md) for full details and examples.

**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).

## Example request

The following cURL command sends a basic email with both a plain-text and an HTML body.

```bash Send an email 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": "Hello from turboSMTP",
    "content": "This is a plain text message.",
    "html_content": "<p>This is an <strong>HTML</strong> message.</p>"
  }'
```

A successful response returns HTTP `200` with the following body:

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

The `mid` field is the turboSMTP message ID, which you can use to look up delivery status in the dashboard or via the analytics API.

## Response codes

| Code | Status | Meaning |
| - | - | - |
| `200` | `OK` | turboSMTP successfully received and queued your message. |
| `400` | `BAD REQUEST` | The request body is malformed or a required parameter is missing or invalid. |
| `401` | `UNAUTHORIZED` | The `consumerKey` or `consumerSecret` is missing, incorrect, or you used an `Authorization` header instead. |
| `500` | `SERVER_UNAVAILABLE` | An unexpected error occurred. Before retrying a send, check whether the message was queued to avoid duplicate mail. |

An error response body looks like this:

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

## Next steps

> [card] [Code Examples](/docs/sending/code-examples.md)
>
> Copy-paste examples for cURL, Python, Node.js, PHP, Ruby, Go, Java, and C#.

> [card] [Attachments](/docs/sending/attachments.md)
>
> Learn how to attach PDFs, images, and other files using Base64 encoding.


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