Send Email With Template

Use this endpoint to send transactional emails using a pre-defined template in SendX with variable substitution. 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/template

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 used for personalization — see Personalization & Merge Tags).
`replyTo`	object	No	Reply-to address. Includes `email` and optionally `name`.
`subject`	string	Yes	Override the template’s default subject line.
`template`	string	Yes	Template identifier (e.g. `template_f3lJvTEhSjKGVb5Lwc5SWS`).

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 -X POST "https://api.sendx.io/api/v1/rest/send/template" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ \
    "from": { \
      "email": "support@example.com" \
    }, \
    "to": [ \
      { \
        "email": "user@example.com", \
        "customFields": { \
          "first_name": "Jane", \
          "order_id": "A12345" \
        } \
      } \
    ], \
    "template": "order-confirmation-template",
    "headers": {
      "X-Campaign": "order-confirmation",
      "List-ID": "template-orders"
    },
    "trackClicks": true,
    "trackOpens": true
}'

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/template)

Same as POST /send/email, plus the following template-specific scenarios:

HTTP Status	Scenario	Response `message`
202	Request valid; email queued	`"Email queued for delivery"` (with `"status": "success"`)
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	Invalid from 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	Template not found, invalid, or missing	`"Template does not exist: template not found or invalid template id"`
400	Recipient email empty	`"Invalid recipient email address: recipient email is required"`
400	Recipient email invalid 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	Invalid request body	`"invalid request body"`
429	Sending limit exceeded	Same messages as POST /send/email
500	Server error	Same messages as POST /send/email

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 is invalid	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.
`Template does not exist: template not found or invalid template id`	Template ID invalid, missing, or template deleted	Verify the template identifier (e.g. `template_f3lJvTEhSjKGVb5Lwc5SWS`) exists in your account.
`Invalid recipient email address: recipient email is required`	A recipient has empty email	Ensure each `to` item has a non-empty `email` field.
`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, template).
`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.
5xx server errors	Temporary server issues	Retry later; if they persist, contact support.

Documentation

Getting Started

Quickstart

Send Email With Template