# Quickstart: send your first email

Canonical URL: https://sendbunny.co/docs/quickstart

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.

## 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](https://sendbunny.co/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](https://docs.aws.amazon.com/ses/latest/dg/send-an-email-from-console.html) address like `success@simulator.amazonses.com`.

**curl:**

```bash
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:**

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

## Troubleshooting

| Status | Error | Fix |
| --- | --- | --- |
| 401 | `Invalid API key` | Send 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. |
| 403 | `This API key is not allowed to send from that domain` | The `from` domain is not in this key's allowed domains. The response lists `allowedRootDomains`; use one of those or issue a new key. |
| 403 | `From address is not a verified sender identity` | Complete domain verification in the dashboard for the `from` domain (DNS records must be live). |
| 400 | `'subject' is required` and similar | Field validation failed — the error message names the exact field. See the [API reference](https://sendbunny.co/docs/send-email-api) for the full request contract. |
| 422 | `Recipient is on the suppression list` | The recipient previously bounced, complained, or was manually suppressed. Remove them in dashboard → Suppression only if you are certain the address is deliverable. |
| 502 | SES error message | SES rejected the send — most often sandbox mode (unverified recipient) or sending-quota limits. The message is passed through from SES. |

## Next steps

- [Full API reference](https://sendbunny.co/docs/send-email-api) — every route, scope, and error.
- [Interactive reference](https://sendbunny.co/docs/reference) — language-tab snippets generated from OpenAPI.
- [For AI agents](https://sendbunny.co/docs/agents) — skill page.
- [Email templates](https://sendbunny.co/docs/email-templates) — `templateAlias` + `data`.
- [OpenAPI spec](https://sendbunny.co/openapi.json) — machine-readable contract.