Send Email

Use this endpoint to send transactional emails to specified recipients with support for personalization, attachments, and tracking. The API returns 202 Accepted when your email is queued for delivery. Actual sending happens in the background. A 202 response means your request was accepted—it does not guarantee delivery. Per-recipient status is not returned in the response.

Endpoint

POST https://api.sendx.io/api/v1/rest/send/email

Headers

Header	Value	Required	Description
Content-Type	`application/json`	Yes	Request body format
X-Team-ApiKey	`YOUR_API_KEY`	Yes	Your SendX Team API key
List-Unsubscribe	`mailto:...` or URL	No	Passed through for list-unsubscribe
X-SendPost-Mock-Email	`true`	No	Mock send (if supported)

Request Body

Field	Type	Required	Description
`from`	object	Yes	Sender info. Must include `email` (string). Optionally include `name`. If the sending domain is whitelisted (verified), any address at that domain and any display name can be used.
`to`	array	Yes	Array of recipients. Each must include `email`. Optionally `name` and `customFields` (key-value pairs).
`replyTo`	object	No	Reply-to address. Includes `email` and optionally `name`.
`subject`	string	Yes	Email subject line.
`htmlBody`	string	Yes	HTML content of the email.
`textBody`	string	No	Plain text fallback content.
`headers`	object	No	Custom headers as key-value pairs. These are passed through in webhook events.

Sender and domain whitelisting: If a sending domain is whitelisted (verified) in SendX, you can use any from email address at that domain and any display name. For example, with domain example.com verified, both support@example.com and orders@example.com are valid, with any name.

Example Request

curl --request POST \
  --url https://api.sendx.io/api/v1/rest/send/email \
  --header 'Content-Type: application/json' \
  --header 'X-Team-ApiKey: <YOUR_TEAM_API_KEY>' \
  --data '{
    "from": {
      "email": "support@example.com",
      "name": "Support Team"
    },
    "to": [
      {
        "email": "jane@example.com",
        "name": "Jane Doe",
        "customFields": {
          "order_id": "A12345"
        }
      }
    ],
    "replyTo": {
      "email": "reply@example.com",
      "name": "Reply Name"
    },
    "subject": "Your Order Confirmation",
    "htmlBody": "<h1>Hi Jane!</h1><p>Your order {{order_id}} has been confirmed.</p>",
    "textBody": "Hi Jane! Your order {{order_id}} has been confirmed.",
    "headers": {
      "X-Custom-Header": "Value"
    }
  }'

Success Response (202 Accepted)

When all validations pass and the message is successfully queued for delivery:

{
  "status": "success",
  "message": "Email queued for delivery"
}

Field	Type	Description
`status`	string	`"success"`
`message`	string	`"Email queued for delivery"`

Note: Delivery happens in the background. A 202 does not guarantee delivery. We automatically retry failed sends. You can check delivery status in your SendX dashboard.

Error Response Format

All error responses use the same JSON shape:

{
  "status": "error",
  "message": "<human-readable error message>"
}

The HTTP status code varies by scenario. Use the exact message values below for debugging and programmatic handling.

Error Scenarios (POST /send/email)

HTTP Status	Scenario	Response `message`
400	No recipients	`"no recipients specified"`
400	From email missing	`"from email is required"`
400	From email invalid format	`"from email must be a valid email address"`
400	From email has no valid domain	`"invalid from email domain"` or `"from email must be a valid email address"`
400	Sender domain not whitelisted	`"From email not whitelisted. Please add and verify the domain first."`
400	Transactional add-on not active	`"Transactional email add-on is not active. Please activate it first at https://app.sendx.io/setting/addons."`
400	At least one recipient has invalid email format	`"Invalid recipient email address: invalid email format"`
401	Missing or invalid team API key	`"The Team ID or API Key specified is not valid"`
422	Request body is not valid JSON or does not match schema	`"invalid request body"`
429	Account email limit reached (zero remaining)	`"Account email sending limit exceeded. Please upgrade your plan."`
429	Recipient count exceeds remaining account limit	`"Account email sending limit exceeded. Current api has {N} contacts, but only {M} emails can be sent."`
429	Recipient count exceeds contact limit	`"Contact limit exceeded. Current api has {N} contacts, but only {M} emails can be sent."`
500	Server error	`"error getting account email sending status"`
500	Server error	`"error getting team add-on"`
500	Server error	`"error while retrieving domains"`
500	Server error	`"Error unmarshalling team add-on setting"`
500	Server error	`"Error getting default provider"`
500	Server error	`"Failed to prepare email payload"`
500	Server error	`"Failed to queue email for delivery"`

Debugging Error Responses

If you see…	Likely cause	What to do
`no recipients specified`	`to` array is empty or missing	Ensure `to` has at least one recipient with a valid `email`.
`from email is required`	`from.email` is missing	Include `from.email` in the request body.
`from email must be a valid email address`	`from.email` format invalid or domain malformed	Use a valid email format (e.g. `user@domain.com`).
`invalid from email domain`	`from` has no valid domain	Use a properly formatted email with a valid domain.
`From email not whitelisted...`	Sender domain not verified	Add and verify the domain in SendX Settings.
`Transactional email add-on is not active`	Add-on not enabled	Activate the transactional add-on at https://app.sendx.io/setting/addons.
`Invalid recipient email address: invalid email format`	One or more `to` emails are invalid	Validate each recipient email format.
`The Team ID or API Key specified is not valid`	Missing or invalid `X-Team-ApiKey`	Check your API key in SendX Settings → Team API Key.
`invalid request body`	Invalid request format	Ensure the body is valid JSON and includes all required fields (from, to, subject, htmlBody).
`Account email sending limit exceeded...`	Plan limit reached	Upgrade your plan or wait for the limit to reset.
`Contact limit exceeded...`	Recipient count exceeds contact limit	Reduce the number of recipients or upgrade.
`error getting account email sending status`	Temporary server issue	Retry later; if it persists, contact support.
`error getting team add-on`	Temporary server issue	Retry later; if it persists, contact support.
`error while retrieving domains`	Temporary server issue	Retry later; if it persists, contact support.
`Error unmarshalling team add-on setting`	Temporary server issue	Retry later; if it persists, contact support.
`Error getting default provider`	Configuration issue	Check SendX settings; contact support if needed.
`Failed to prepare email payload`	Temporary server issue	Retry; if it persists, contact support.
`Failed to queue email for delivery`	Temporary server issue	Retry; if it persists, contact support.

Documentation

Getting Started

Quickstart

Send Email

Send Email

Endpoint

Headers

Request Body

Example Request

Success Response (202 Accepted)

Error Response Format

Error Scenarios (POST /send/email)

Debugging Error Responses

​Send Email

​Endpoint

​Headers

​Request Body

​Example Request

​Success Response (202 Accepted)

​Error Response Format

​Error Scenarios (POST /send/email)

​Debugging Error Responses

Send Email

Endpoint

Headers

Request Body

Example Request

Success Response (202 Accepted)

Error Response Format

Error Scenarios (POST /send/email)

Debugging Error Responses