Sending Emails

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.
`html`	string	No	HTML body. At least one of `html` or `text` required.
`text`	string	No	Plain text body.
`reply_to`	object	No	Reply-to address with `email` and optional `name`.
`headers`	object	No	Custom email headers.
`tags`	array	No	Tags for categorization and filtering.
`send_at`	string	No	ISO 8601 datetime for scheduled sending (Starter plan and above).

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, invalid sender), it contains a string describing the reason.

Email statuses

Status	Description
`queued`	Email accepted and queued for sending
`sent`	Email handed off to the mail server
`delivered`	Email accepted by the recipient's server
`bounced`	Email rejected by the recipient's server
`scheduled`	Email scheduled for future delivery
`cancelled`	Scheduled email was cancelled
`failed`	Email could not be sent (validation error, etc.)

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`

List emails

curl "https://send.esmsafrica.io/v1/emails/?page=1&limit=50" \
  -H "Authorization: Bearer esms_k_your_api_key"

Supports filtering by status, tag, date range, and search.

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 including all delivery events (sent, delivered, opened, clicked, 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

eSMS Mail provides a WebSocket endpoint for real-time email status updates:

wss://send.esmsafrica.io/ws/emails

Events include email_status (status changes), email_new (new emails), and forward_new (forwarded emails).

Sending Emails

On this page