eSMS AfricaeSMS Africa
eSMS Mail

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

FieldTypeRequiredDescription
fromobjectYesSender email and name. Domain must be verified.
toarrayYesArray of recipient objects with email and optional name.
ccarrayNoCarbon copy recipients.
bccarrayNoBlind carbon copy recipients.
subjectstringYes*Email subject line. *Optional when template_id is set (the template's subject is used).
htmlstringNoHTML body. At least one of html or text required (unless template_id is set).
textstringNoPlain text body.
reply_toobjectNoReply-to address with email and optional name.
headersobjectNoCustom email headers (string values). Identity and routing headers such as From, To, Subject and Message-ID cannot be overridden.
tagsarrayNoTags for categorization and filtering.
metadataobjectNoYour own key/values, stored with the email and echoed back in webhook payloads.
streamstringNotransactional (default) or broadcast for marketing/bulk mail. Unsubscribes from broadcast mail never block transactional mail.
template_idstringNoID of one of your templates to render instead of inline html/text.
template_dataobjectNoValues for the template's {{variable}} placeholders.
attachmentsarrayNoFiles as {"filename", "content" (base64), "content_type"}. Up to 10 MB in total. Not supported with send_at.
send_atstringNoISO 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

StatusDescription
queuedEmail accepted and queued for sending
sendingEmail is being handed off to the mail server
sentEmail handed off to the mail server
deliveredEmail accepted by the recipient's server
bouncedEmail rejected by the recipient's server
complainedRecipient marked the email as spam
scheduledEmail scheduled for future delivery
cancelledScheduled email was cancelled
rejectedEmail was not accepted (see rejection_reason), or every recipient was on your suppression list
failedEmail 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:

EventWhenDescription
scheduled_cancelledCancel button or DELETE endpointThe scheduled email was cancelled
scheduled_sentSend-now button or POST send-now endpointThe scheduled email was sent immediately
email_statusScheduler sends it at the scheduled timeStatus 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).

On this page