Transactional email API

SendBunny is self-hosted, so there is no shared API host. Your endpoint is an AWS Lambda function URL unique to your install, shown as Transactional API URL on the dashboard's API Keys page. It looks like https://abc123xyz.lambda-url.us-east-1.on.aws/.

• Method: POST only. Any other method returns 405 { "error": "Method not allowed" }.
• Body: JSON, UTF-8. Send Content-Type: application/json. AWS Lambda caps the request body at ~6 MB; Amazon SES separately caps total message size (10 MB by default).
• One recipient per request. To send to N recipients, make N requests.
• Responses from the API are JSON with Content-Type: application/json. The one exception is 429, which is emitted by AWS Lambda itself when concurrency is capped — don't rely on its body shape.
• Not supported (today): multiple recipients, cc/bcc, replyTo, attachments, and custom headers. Unrecognized JSON fields are silently ignored, so a cc field does not error — it just does nothing.

Every request needs an API key in the Authorization header: Authorization: Bearer sb_.... Keys are created by an ADMIN user in dashboard → API Keys, are shown exactly once at creation (only a SHA-256 hash is stored), and can be revoked at any time.

Each key is scoped to one or more root domains at creation. The key may only send from addresses whose registrable domain is in that list, and may only use templates that belong to those domains. A missing or malformed header returns 401 { "error": "Unauthorized" }; an unknown or revoked key returns 401 { "error": "Invalid API key" }.

Treat keys as server-side secrets. The endpoint sends permissive CORS headers, but calling it from browser JavaScript would expose your key to every visitor — always call it from your backend.

There are two send modes: raw (you provide subject + html/text inline) and template (you reference a stored template by templateId or templateAlias, optionally with data merge variables). Fields from the two modes cannot be mixed.

Templates are created in dashboard → Templates and can be given an alias (e.g. password-reset). Reference one by alias or id, and pass merge variables in data:

curl -X POST 'https://YOUR-INSTALL.lambda-url.us-east-1.on.aws/' \
  -H 'Authorization: Bearer sb_YOUR_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "priya@example.com",
    "templateAlias": "password-reset",
    "data": {
      "name": "Priya",
      "reset_url": "https://app.example.com/reset/abc123"
    }
  }'

If the template has no stored plain-text body, SendBunny derives one from the rendered HTML automatically. Template syntax ({{name}}, {{name|fallback}}) and variable rules are documented in Email templates.

• data must be a JSON object. Values may be strings, numbers, booleans, or nested objects of those. Arrays and null are rejected with a 400 that names the offending paths.
• Nested objects are flattened to dot paths: { "user": { "name": "Priya" } } fills {{user.name}}. Numbers and booleans are converted to strings.
• {{email}} is always available and defaults to the to address; an explicit data.email overrides it.
• Every template variable without an inline fallback must be present in data, otherwise the send is rejected with 400 { "error": "Missing required template variables: ...", "missing": [...] } — SendBunny never sends an email with blank merge fields.

Success is 200 with the SES message id — the same id that later appears in delivery/bounce events in the dashboard:

{ "messageId": "0100018f2ab4c123-2d1e8a77-..." }

All errors are JSON: { "error": "<human-readable message>" }, sometimes with extra machine-readable fields (listed below). The complete set:

• Sends are synchronous: a 200 means Amazon SES accepted the message in your AWS account. Delivery, bounce, open, and click events then flow into your dashboard's deliverability views.
• Your AWS account's SES sending quota and rate apply — they are your own limits, not SendBunny platform limits. Quota-exceeded errors surface as 502 with the SES message.
• Some installs cap the endpoint's concurrency (AWS Lambda reserved concurrency of 10 — an install-time option, not universal). Bursts beyond the cap receive HTTP 429 from AWS before any send happens, so a 429 is always safe to retry with exponential backoff.
• There is no idempotency-key support: a retried request that already succeeded sends a second email. Only retry requests that certainly did not return 200 — treat a client-side timeout as possibly-sent.
• Suppression (bounces, complaints, manual entries) is enforced on every transactional send automatically — expect 422 for suppressed recipients rather than a delivery attempt.