Send Transactional Email: POST /mail/send Reference

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

Global endpoint

POST https://api.turbo-smtp.com/api/v2/mail/send

For EU infrastructure, use:

EU endpoint

POST https://api.eu.turbo-smtp.com/api/v2/mail/send

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.

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

string

required

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

string

required

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

string

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

string

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

string

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

string

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

string

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

object

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

string

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

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 (filter_by=x_campaign_id). The X-Campaign-Id header on the delivered message is internal routing data, not this value.

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.

array

An array of attachment objects. See the Attachment object section below.

Attachment object

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

string

required

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

string

required

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

string

required

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

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.

Example request

Terminal

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

Terminal

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

{
  "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.

Missing or invalid credentials

{
  "errorCode": 3,
  "message": "Invalid authorization token",
  "details": "No authorization key was specified for request: POST /api/mail/send"
}

Invalid recipient address

{
  "message": "error",
  "errors": [
    ["'bad-email' 'to' email not valid"],
    "missing recipients (to)"
  ]
}

Missing sender address

{
  "message": "error",
  "errors": [
    "missing or not valid sender email (from)"
  ]
}

Insufficient sending credits

{
  "message": "error",
  "errors": {
    "message": "error",
    "errors": "nocredit"
  }
}

Deactivated account

{
  "error": 3,
  "message": "Account for test@domain.com is inactive"
}

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.

Overview

Endpoints

Send Transactional Email: POST /mail/send Reference

Endpoint

Request headers

Request body parameters

Attachment object

Example request

Example with attachment

Successful response

Response codes

Error responses

​Endpoint

​Request headers

​Request body parameters

​Attachment object

​Example request

​Example with attachment

​Successful response

​Response codes

​Error responses

Endpoint

Request headers

Request body parameters

Attachment object

Example request

Example with attachment

Successful response

Response codes

Error responses