Sending Emails
Send emails via the eSMS Mail REST API.
Before sending emails, you must create a sender address on a verified domain. The from email in every request must match an active sender address you own.
Send a single email
curl -X POST https://send.esmsafrica.io/v1/emails/ \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": {"email": "hello@yourdomain.com", "name": "Your App"},
"to": [{"email": "user@example.com", "name": "John Doe"}],
"subject": "Welcome to our platform",
"html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
"text": "Welcome! Thanks for signing up.",
"tags": ["welcome", "onboarding"]
}'Request body
| Field | Type | Required | Description |
|---|---|---|---|
from | object | Yes | Sender email and name. Domain must be verified. |
to | array | Yes | Array of recipient objects with email and optional name. |
cc | array | No | Carbon copy recipients. |
bcc | array | No | Blind carbon copy recipients. |
subject | string | Yes* | Email subject line. *Optional when template_id is set (the template's subject is used). |
html | string | No | HTML body. At least one of html or text required (unless template_id is set). |
text | string | No | Plain text body. |
reply_to | object | No | Reply-to address with email and optional name. |
headers | object | No | Custom email headers (string values). Identity and routing headers such as From, To, Subject and Message-ID cannot be overridden. |
tags | array | No | Tags for categorization and filtering. |
metadata | object | No | Your own key/values, stored with the email and echoed back in webhook payloads. |
stream | string | No | transactional (default) or broadcast for marketing/bulk mail. Unsubscribes from broadcast mail never block transactional mail. |
template_id | string | No | ID of one of your templates to render instead of inline html/text. |
template_data | object | No | Values for the template's {{variable}} placeholders. |
attachments | array | No | Files as {"filename", "content" (base64), "content_type"}. Up to 10 MB in total. Not supported with send_at. |
send_at | string | No | ISO 8601 datetime for scheduled sending (Starter plan and above). Must be at least 1 minute and at most 30 days ahead. |
The total number of recipients (to + cc + bcc) is limited to 1,000 per message.
Idempotent retries
Pass an Idempotency-Key header to retry safely. Repeating the same key (per account, within 24 hours) returns the original email instead of sending a duplicate. A retry that arrives while the first request is still processing gets 409 Conflict.
curl -X POST https://send.esmsafrica.io/v1/emails/ \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Idempotency-Key: order-1234-receipt" \
-H "Content-Type: application/json" \
-d '{ ... }'Response
The send endpoint returns HTTP 202 Accepted.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"message_id": "<abc123@send.esmsafrica.io>",
"rejection_reason": null
}The rejection_reason field is null for accepted emails. When an email is rejected (e.g. unverified domain, unregistered sender, plan limit reached), the API still returns 202 with "status": "rejected" and a rejection_reason string describing why - always check status. Malformed requests (missing recipients, invalid JSON) get 422.
Templates
Store reusable content once and send it by ID (Starter plan and above). {{variable}} placeholders are filled from template_data:
# Create a template
curl -X POST https://send.esmsafrica.io/v1/templates/ \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Content-Type: application/json" \
-d '{"name": "welcome", "subject": "Welcome, {{name}}", "html_body": "<p>Hi {{name}}, thanks for joining.</p>"}'
# Send it
curl -X POST https://send.esmsafrica.io/v1/emails/ \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": {"email": "hello@yourdomain.com"},
"to": [{"email": "user@example.com"}],
"template_id": "your_template_id",
"template_data": {"name": "Ada"}
}'Manage templates with GET /v1/templates/, GET/PATCH/DELETE /v1/templates/{template_id} and POST /v1/templates/{template_id}/duplicate.
Email statuses
| Status | Description |
|---|---|
queued | Email accepted and queued for sending |
sending | Email is being handed off to the mail server |
sent | Email handed off to the mail server |
delivered | Email accepted by the recipient's server |
bounced | Email rejected by the recipient's server |
complained | Recipient marked the email as spam |
scheduled | Email scheduled for future delivery |
cancelled | Scheduled email was cancelled |
rejected | Email was not accepted (see rejection_reason), or every recipient was on your suppression list |
failed | Email could not be handed off for delivery |
Scheduled sending
Send an email at a future time by including the send_at field with an ISO 8601 datetime:
curl -X POST https://send.esmsafrica.io/v1/emails/ \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": {"email": "hello@yourdomain.com", "name": "Your App"},
"to": [{"email": "user@example.com"}],
"subject": "Tomorrow morning briefing",
"html": "<p>Your daily briefing...</p>",
"send_at": "2025-01-16T08:00:00Z"
}'The email status will be scheduled until the scheduled time, then it moves to queued and sends automatically.
Scheduled sending requires the Starter plan or above. Free plan users receive a 403 error.
List scheduled emails
curl https://send.esmsafrica.io/v1/emails/scheduled \
-H "Authorization: Bearer esms_k_your_api_key"Each scheduled email includes a seconds_until_send countdown.
Cancel a scheduled email
curl -X DELETE https://send.esmsafrica.io/v1/emails/scheduled/{email_id} \
-H "Authorization: Bearer esms_k_your_api_key"The email status changes to cancelled. Emails that have already been sent cannot be cancelled.
Send now (skip the schedule)
Send a scheduled email immediately instead of waiting for the scheduled time:
curl -X POST https://send.esmsafrica.io/v1/emails/scheduled/{email_id}/send-now \
-H "Authorization: Bearer esms_k_your_api_key"The email moves from scheduled to queued and sends right away.
Scheduled email WebSocket events
The WebSocket at wss://send.esmsafrica.io/ws/emails emits these events for scheduled emails:
| Event | When | Description |
|---|---|---|
scheduled_cancelled | Cancel button or DELETE endpoint | The scheduled email was cancelled |
scheduled_sent | Send-now button or POST send-now endpoint | The scheduled email was sent immediately |
email_status | Scheduler sends it at the scheduled time | Status changes from scheduled → queued → sent → delivered |
Batch sending
Send up to 100 different emails in one call (Starter plan and above). The body is a JSON array of the same objects you would POST to /v1/emails/:
curl -X POST https://send.esmsafrica.io/v1/emails/batch \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Content-Type: application/json" \
-d '[
{"from": {"email": "hello@yourdomain.com"}, "to": [{"email": "a@example.com"}], "subject": "Hi A", "text": "Hello A"},
{"from": {"email": "hello@yourdomain.com"}, "to": [{"email": "b@example.com"}], "subject": "Hi B", "text": "Hello B"}
]'{
"total": 2,
"sent": 2,
"failed": 0,
"results": [
{"id": "550e8400-e29b-41d4-a716-446655440000", "status": "queued", "rejection_reason": null},
{"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "status": "queued", "rejection_reason": null}
]
}Batch items use inline subject/html/text; send templated emails one at a time with POST /v1/emails/.
Validate addresses
Check up to 100 recipient addresses before sending - syntax, disposable providers, role mailboxes and whether the domain can receive mail (MX):
curl -X POST https://send.esmsafrica.io/v1/emails/validate \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Content-Type: application/json" \
-d '{"emails": ["user@example.com", "info@mailinator.com"]}'The response has a summary (total, deliverable, undeliverable, risky, unknown) and a per-address results array.
List emails
curl "https://send.esmsafrica.io/v1/emails/?page=0&limit=50" \
-H "Authorization: Bearer esms_k_your_api_key"page is zero-based (the first page is 0) and limit defaults to 20 (maximum 100). Filter with status (e.g. ?status=bounced) and environment (live - the default, test or all; test API keys always see only test emails).
To search by recipient, sender or subject, or filter by tag, use the search endpoint:
curl "https://send.esmsafrica.io/v1/emails/search?q=invoice&tag=billing&page=0&limit=20" \
-H "Authorization: Bearer esms_k_your_api_key"Get email details
curl https://send.esmsafrica.io/v1/emails/{email_id} \
-H "Authorization: Bearer esms_k_your_api_key"Returns the full email details (bodies, headers, message_id) including all its events (queued, sent, delivered, open, click, bounced, ...).
Get email events
curl https://send.esmsafrica.io/v1/emails/{email_id}/events \
-H "Authorization: Bearer esms_k_your_api_key"Real-time updates
The eSMS Mail dashboard uses a WebSocket endpoint for real-time email status updates:
wss://send.esmsafrica.io/ws/emails?token=<dashboard_session_token>It authenticates with a dashboard login session (the token query parameter or the session cookie), not with an API key. Server-side integrations should use webhooks instead.
Events include email_status (status changes), email_new (new emails), and forward_new (forwarded emails).