> ## 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 > Use the SendX API to send transactional emails with personalization, custom headers, and tracking. ## 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 ```bash theme={null} curl --request POST \ --url https://api.sendx.io/api/v1/rest/send/email \ --header 'Content-Type: application/json' \ --header 'X-Team-ApiKey: ' \ --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": "

Hi Jane!

Your order {{order_id}} has been confirmed.

", "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: ```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/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](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. |