> ## Documentation Index > Fetch the complete documentation index at: https://docs.sendx.io/llms.txt > Use this file to discover all available pages before exploring further. # Send Email With Template > Send emails using pre-defined templates in SendX with variable substitution and tracking. ## 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](/api-reference/email-sending/personalization)). | | `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 ```bash theme={null} 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: ```json theme={null} { "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: ```json theme={null} { "status": "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](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. |