Skip to main content

​
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

HeaderValueRequiredDescription
Content-Typeapplication/jsonYesRequest body format
X-Team-ApiKeyYOUR_API_KEYYesYour SendX Team API key
List-Unsubscribemailto:... or URLNoPassed through for list-unsubscribe
X-SendPost-Mock-EmailtrueNoMock send (if supported)

​
Request Body

FieldTypeRequiredDescription
fromobjectYesSender 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.
toarrayYesArray of recipients. Each must include email. Optionally name and customFields (key-value pairs).
replyToobjectNoReply-to address. Includes email and optionally name.
subjectstringYesOverride the template’s default subject line.
templatestringYesTemplate 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"
}
FieldTypeDescription
statusstring"success"
messagestring"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 StatusScenarioResponse message
202Request valid; email queued"Email queued for delivery" (with "status": "success")
400No recipients"no recipients specified"
400From email missing"from email is required"
400From email invalid format"from email must be a valid email address"
400Invalid from domain"invalid from email domain" or "from email must be a valid email address"
400Sender domain not whitelisted"From email not whitelisted. Please add and verify the domain first."
400Transactional add-on not active"Transactional email add-on is not active. Please activate it first at https://app.sendx.io/setting/addons."
400Template not found, invalid, or missing"Template does not exist: template not found or invalid template id"
400Recipient email empty"Invalid recipient email address: recipient email is required"
400Recipient email invalid format"Invalid recipient email address: invalid email format"
401Missing or invalid team API key"The Team ID or API Key specified is not valid"
422Invalid request body"invalid request body"
429Sending limit exceededSame messages as POST /send/email
500Server errorSame messages as POST /send/email

​
Debugging Error Responses

If you see…Likely causeWhat to do
no recipients specifiedto array is empty or missingEnsure to has at least one recipient with a valid email.
from email is requiredfrom.email is missingInclude from.email in the request body.
from email must be a valid email addressfrom.email format is invalidUse a valid email format (e.g. user@domain.com).
invalid from email domainfrom has no valid domainUse a properly formatted email with a valid domain.
From email not whitelisted...Sender domain not verifiedAdd and verify the domain in SendX Settings.
Transactional email add-on is not activeAdd-on not enabledActivate the transactional add-on at https://app.sendx.io/setting/addons.
Template does not exist: template not found or invalid template idTemplate ID invalid, missing, or template deletedVerify the template identifier (e.g. template_f3lJvTEhSjKGVb5Lwc5SWS) exists in your account.
Invalid recipient email address: recipient email is requiredA recipient has empty emailEnsure each to item has a non-empty email field.
Invalid recipient email address: invalid email formatOne or more to emails are invalidValidate each recipient email format.
The Team ID or API Key specified is not validMissing or invalid X-Team-ApiKeyCheck your API key in SendX Settings → Team API Key.
invalid request bodyInvalid request formatEnsure the body is valid JSON and includes all required fields (from, to, subject, template).
Account email sending limit exceeded...Plan limit reachedUpgrade your plan or wait for the limit to reset.
Contact limit exceeded...Recipient count exceeds contact limitReduce the number of recipients or upgrade.
5xx server errorsTemporary server issuesRetry later; if they persist, contact support.