sendbunnySendbunny
.md

Quickstart: send your first email

This guide takes you from a fresh SendBunny install to a delivered transactional email. Every step is explicit — no context is assumed beyond the prerequisites listed below.

Last updated

Prerequisites

  • A SendBunny install in your AWS account. SendBunny is self-hosted: there is no shared SaaS endpoint. If you have not installed it yet, see Deploy — installation is a pre-filled CloudFormation template and takes about 10 minutes.
  • Admin access to your SendBunny dashboard. The install emails the first admin a temporary password. API keys can only be created by users in the ADMIN role.
  • A verified sender domain. In the dashboard, open your domain's onboarding page and complete DNS setup (DKIM/SPF/DMARC records). The API refuses to send from unverified addresses with HTTP 403.
  • SES production access (for real recipients). New AWS accounts start in the SES sandbox, which only delivers to verified recipient addresses. The dashboard includes a wizard for requesting production access. In the sandbox, sends to unverified recipients fail with HTTP 502.

Step 1 — Create an API key

  • In your SendBunny dashboard, go to API Keys (left sidebar).
  • Click Create key, name it, leave the default email:send scope (or add more), and confirm the sending domain. A key can only act on the root domains it was issued for.
  • Copy the key immediately. It starts with sb_ and is shown exactly once — SendBunny stores only a hash. If you lose it, revoke it and create a new one.

Step 2 — Copy your API URL

Because SendBunny runs in your own AWS account, your API endpoint is unique to your install. The API keys page shows a CloudFront URL. All calls go under /v1. Send is POST /v1/emails.

Step 3 — Send an email

Replace the URL, the key, and from (must be an address on a domain you verified — see prerequisites — and allowed for this key in Step 1). In the SES sandbox, to must be a verified recipient or an SES mailbox simulator address like success@simulator.amazonses.com.

curl
curl -X POST 'https://YOUR-DISTRIBUTION.cloudfront.net/v1/emails' \
  -H 'x-api-key: sbYOUR_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["success@simulator.amazonses.com"],
    "subject": "Hello from SendBunny",
    "html": "<p>It works!</p>"
  }'

A successful send returns HTTP 200 with the SES message id:

Response
{ "messageId": "0100018f2ab4c123-...", "id": "a1b2c3d4-..." }

Troubleshooting

StatusErrorFix
401Invalid API keySend the key in the x-api-key header (Authorization: Bearer also works). Check the key was not revoked; a brand-new key can take a minute to become active.
403This API key is not allowed to send from that domainThe from domain is not in this key's allowed domains. The response lists allowedRootDomains; use one of those or issue a new key.
403From address is not a verified sender identityComplete domain verification in the dashboard for the from domain (DNS records must be live).
400'subject' is required and similarField validation failed — the error message names the exact field. See the API reference for the full request contract.
422Recipient is on the suppression listThe recipient previously bounced, complained, or was manually suppressed. Remove them in dashboard → Suppression only if you are certain the address is deliverable.
502SES error messageSES rejected the send — most often sandbox mode (unverified recipient) or sending-quota limits. The message is passed through from SES.

Next steps

NextHTTP API