Skip to main content

​
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

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.
subjectstringYesEmail subject line.
htmlBodystringYesHTML content of the email.
textBodystringNoPlain text fallback content.
headersobjectNoCustom 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"
}
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/email)

HTTP StatusScenarioResponse message
400No recipients"no recipients specified"
400From email missing"from email is required"
400From email invalid format"from email must be a valid email address"
400From email has no valid 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."
400At least one recipient has invalid email format"Invalid recipient email address: invalid email format"
401Missing or invalid team API key"The Team ID or API Key specified is not valid"
422Request body is not valid JSON or does not match schema"invalid request body"
429Account email limit reached (zero remaining)"Account email sending limit exceeded. Please upgrade your plan."
429Recipient count exceeds remaining account limit"Account email sending limit exceeded. Current api has {N} contacts, but only {M} emails can be sent."
429Recipient count exceeds contact limit"Contact limit exceeded. Current api has {N} contacts, but only {M} emails can be sent."
500Server error"error getting account email sending status"
500Server error"error getting team add-on"
500Server error"error while retrieving domains"
500Server error"Error unmarshalling team add-on setting"
500Server error"Error getting default provider"
500Server error"Failed to prepare email payload"
500Server error"Failed to queue email for delivery"

​
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 invalid or domain malformedUse 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.
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, htmlBody).
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.
error getting account email sending statusTemporary server issueRetry later; if it persists, contact support.
error getting team add-onTemporary server issueRetry later; if it persists, contact support.
error while retrieving domainsTemporary server issueRetry later; if it persists, contact support.
Error unmarshalling team add-on settingTemporary server issueRetry later; if it persists, contact support.
Error getting default providerConfiguration issueCheck SendX settings; contact support if needed.
Failed to prepare email payloadTemporary server issueRetry; if it persists, contact support.
Failed to queue email for deliveryTemporary server issueRetry; if it persists, contact support.