API Reference

The Sendex API lets you send and receive email programmatically using your verified domains. All endpoints follow RESTful conventions and return JSON.

Authentication

Every request must include your API key in the Authorization header as a Bearer token. Generate keys from the API Keys section of your dashboard.

Authorization: Bearer sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Rate Limits

Rate limits are enforced per API key. Exceeding the limit returns 429 Too Many Requests. The underlying AWS SES sending limits apply to outbound mail regardless of API limits.

Delivery & Retries

Sendex uses an internal queue between your API call and the actual SES send. This decouples your request from the network call to AWS, so transient SES failures are handled automatically without any effort on your side.

How it works

1. Your POST /api/v1/emails request returns 202 Accepted immediately — the email is queued, not yet sent.
2. A background worker picks up the job and sends it to AWS SES.
3. If SES returns an error, the job is automatically retried with exponential backoff.
4. Once sent (or permanently failed), a webhook fires so you know the outcome.

Retry schedule

Errors

All errors return a JSON body with error (machine-readable slug) and message (human-readable string).

{
  "error": "bad_request",
  "message": "from, to, subject, and text or html are required."
}

Webhooks

Webhooks allow Sendex to push real-time event notifications to your server. Register endpoints from the Webhooks section of your dashboard.

Payload format

Every webhook request is an HTTP POST with a JSON body and a signature header.

POST https://your-server.com/webhook
Content-Type: application/json
X-Sendex-Signature: sha256=<hmac-sha256-hex>

{
  "event": "email.sent",
  "created_at": "2026-03-05T12:00:00.000Z",
  "data": { ... }
}

Verifying signatures

Compute HMAC-SHA256(secret, rawBody) and compare it to the value in the X-Sendex-Signature header (after stripping the sha256= prefix). Use a timing-safe comparison.

import crypto from "crypto";

function verifyWebhook(rawBody: string, secret: string, header: string): boolean {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(header),
    Buffer.from(expected)
  );
}

Events

SES delivery events setup

Events like email.delivered, email.bounced, and email.complained require an AWS SES Configuration Set with an SNS destination pointing to /api/ses-notifications. Set the SES_CONFIG_SET environment variable to the name of your configuration set.