eSMS AfricaeSMS Africa
eSMS Mail

Webhooks

Receive real-time notifications for email delivery events.

Webhooks send HTTP POST requests to your server when email events occur - delivery, bounce, open, click, etc.

Create a webhook

Via dashboard

Go to Settings → Webhooks and click Create. Enter your endpoint URL and select which events to receive.

Via API

curl -X POST https://send.esmsafrica.io/v1/webhooks/ \
  -H "Authorization: Bearer esms_k_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/email",
    "events": ["delivered", "bounced", "open", "click"]
  }'

Response includes a secret for verifying webhook signatures:

{
  "id": "3f2b8c1e-6d4a-4b7e-9a51-2c8d0e7f4a19",
  "url": "https://yourapp.com/webhooks/email",
  "events": ["delivered", "bounced", "open", "click"],
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "is_active": true,
  "created_at": "2026-07-31T10:00:00Z"
}

Use the exact event names from Available events - a webhook only receives the events listed in its events array. The URL must be a public http(s) address. List your webhooks with GET /v1/webhooks/.

Webhook payload

{
  "event_type": "delivered",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-07-31T10:30:00Z",
  "metadata": { "order_id": "1234" },
  "data": { "recipient": "user@example.com", "response": "250 2.0.0 OK" }
}

metadata is whatever you passed as metadata when sending (or {}). The data object depends on the event: delivered, bounced and complained carry recipient and the receiving server's response; sent carries recipients; failed carries error; click carries the clicked url; sandbox events carry "livemode": false.

Each request also carries these headers: X-ESMS-Signature (HMAC-SHA256 of the raw body), X-ESMS-Event (the event type), and X-ESMS-Delivery-ID. Non-2xx responses are retried with backoff (1m, 5m, 30m, 2h, 8h). Endpoints that resolve to private/internal addresses are rejected.

Verifying signatures

Each webhook request includes an X-ESMS-Signature header containing an HMAC-SHA256 signature. Verify it using the webhook secret:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from('sha256=' + expected)
  );
}
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest('sha256=' + expected, signature)

Available events

EventDescription
sentEmail accepted by eSMS Mail's mail server for delivery
deliveredEmail accepted by recipient's server
bouncedEmail rejected by recipient's server
complainedRecipient marked the email as spam (feedback loop)
openRecipient opened the email
clickRecipient clicked a link
failedEmail could not be sent

Managing webhooks

Update a webhook

curl -X PATCH https://send.esmsafrica.io/v1/webhooks/{webhook_id} \
  -H "Authorization: Bearer esms_k_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"events": ["delivered", "bounced"], "is_active": true}'

Delete a webhook

curl -X DELETE https://send.esmsafrica.io/v1/webhooks/{webhook_id} \
  -H "Authorization: Bearer esms_k_your_api_key"

Delivery log and resend

Every delivery attempt is logged:

# Recent deliveries for one webhook
curl https://send.esmsafrica.io/v1/webhooks/{webhook_id}/deliveries \
  -H "Authorization: Bearer esms_k_your_api_key"

# One delivery, including the payload and your endpoint's response
curl https://send.esmsafrica.io/v1/webhooks/deliveries/{delivery_id} \
  -H "Authorization: Bearer esms_k_your_api_key"

# Send it again
curl -X POST https://send.esmsafrica.io/v1/webhooks/deliveries/{delivery_id}/resend \
  -H "Authorization: Bearer esms_k_your_api_key"

Retry policy

If your endpoint returns a non-2xx status code, eSMS Mail retries the delivery up to 5 times with backoff (1m, 5m, 30m, 2h, 8h). Failed webhooks are logged and can be inspected in the dashboard or via the delivery log above.

On this page