# Testing

Build and test your email code, and your webhook handling, without sending real mail. Groundmail has two tools for this:

- **Test keys** (`gm_test_…`): the API works exactly as it does with a live key, but nothing is delivered.
- **Simulator addresses** (`…@simulator.groundmail.dev`): each one produces a specific outcome, such as a hard bounce or a spam complaint, with real webhooks. They work with test keys and live keys.

Neither touches your sending reputation, your stats or your bill.

## Test mode in the dashboard

The **Live | Test** switch in the top bar changes what the dashboard shows. In Test mode, Home, Emails, Analytics, API keys, SMTP, automation runs and webhook deliveries show test data only, with their own counts. Live mode never shows it. Domains, templates, tenants, suppressions and settings are shared by both.

The mode is part of the page address (`?mode=test`), so you can share a link to it. A new session starts in Live.

## Test keys

Create a test key on the [API keys](https://app.groundmail.dev/api-keys) page (in Test mode, or tick **Test key**), or through the API:

```bash
curl -X POST https://api.groundmail.dev/api-keys \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI", "scopes": ["emails:send", "emails:read"], "test": true}'
```

```bash
groundmail keys create --name CI --scopes emails:send,emails:read --test
```

```ts
const key = await groundmail.apiKeys.create({ name: 'CI', scopes: ['emails:send', 'emails:read'], test: true })
```

The `token` in the response starts with `gm_test_`. A test key has scopes like any other key, and is listed on the API keys page in Test mode.

### What a test send does

A send with a test key runs the whole pipeline:

- Request validation, templates and variables, `Idempotency-Key`, scheduled sends (`scheduled_at`) and batch sends.
- The checks a live send gets: your `from` domain must be verified (or the sandbox address), suppressed and opted-out recipients are refused, and [Groundmail validation](https://docs.groundmail.dev/validation) holds back addresses that cannot receive mail.

Then, instead of handing the message to the mail server, Groundmail marks it delivered and fires the same webhooks a real delivery would. The response says so:

```json
{ "id": "msg_…", "status": "sent", "test": true }
```

The email is stored like any other, with `"test": true`. Switch the dashboard to **Test** to see it on the Emails page; Live never shows test emails (`GET /emails?test=true` in the API). Its webhook events carry `"test": true` in `data`.

Test sends **do not count** toward your plan's monthly or daily volume, the [new account ramp-up](https://docs.groundmail.dev/sending-limits#new-account-ramp-up), deliverability stats, or billing. They are not stopped by those limits either.

A test key never delivers. An accepted test send to a real address reports `delivered` without sending anything. To see a simulated bounce or complaint, send to a simulator address.

Real addresses still follow the recipient limits of a live send. Until you verify a domain and add a payment method, a test send to anyone but your account email is refused with the same error as a live one, and over SMTP with `554`. Simulator addresses work on any plan, so use those on an unpaid account.

Good to know:

- An `Idempotency-Key` used with a test key never matches one used with a live key.
- Resending a test email (`POST /emails/{id}/resend`, or **Resend** in the dashboard) sends a test email again.
- Events sent with a test key (`POST /events`) start test runs of your [automations](https://docs.groundmail.dev/automations): their emails are test sends and their SMS steps are skipped. A test event never resumes or cancels a live run.
- SMTP credentials can be test credentials too (`gmsmtp_test_…`): see [Test SMTP credentials](#test-smtp-credentials). Simulator addresses also work over a live SMTP credential.

## Test SMTP credentials

If your app sends over SMTP, create a test credential on the [SMTP](https://app.groundmail.dev/smtp?mode=test) page in Test mode, or with `POST /smtp-credentials` and `"test": true`. The password starts with `gmsmtp_test_`; the host, port and username are the same as live.

Every message sent with it is a test send, exactly as with a test key, including the limit on real addresses above. When you go to production, create a live credential and swap the password.

## Simulator addresses

Send to these addresses to get a specific outcome. They work with a live key or a test key, from your verified domain or the sandbox address, and on any plan.

| Address | Outcome | Status | Webhooks |
|---------|---------|--------|----------|
| `delivered@simulator.groundmail.dev` | Delivered | `delivered` | `email.delivered` |
| `bounce@simulator.groundmail.dev` | Hard bounce: the mailbox does not exist | `bounced`, `bounce_type: "hard"` | `email.bounced` |
| `block@simulator.groundmail.dev` | Block bounce: the receiving server refused the sender | `bounced`, `bounce_type: "block"` | `email.bounced` |
| `complaint@simulator.groundmail.dev` | Delivered, then marked as spam | `complained` | `email.delivered`, then `email.complained` a few seconds later |
| `suppressed@simulator.groundmail.dev` | Treated as a suppressed recipient | `suppressed` (the send returns 422) | `email.suppressed` |
| `delayed@simulator.groundmail.dev` | The receiving server deferred delivery | `delayed` | `email.delivery_delayed` |

Plus addressing works, so you can tell your tests apart: `bounce+signup-42@simulator.groundmail.dev` hard-bounces like `bounce@`. Any other address at `simulator.groundmail.dev` is refused with a 400 `validation_error`.

`simulator.groundmail.dev` has an MX record, so apps that check whether an address's domain can receive email (newsletter tools, signup forms) accept simulator addresses as contacts. Only email sent through Groundmail is simulated: mail sent to these addresses from anywhere else is refused, and the domain's SPF record allows no senders.

```bash
curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "bounce+signup-42@simulator.groundmail.dev",
    "subject": "Bounce handling test",
    "html": "<p>Simulated.</p>"
  }'
```

```ts
import { simulatorAddress } from 'groundmail'

await groundmail.emails.send({
  from: 'you@yourdomain.com',
  to: simulatorAddress('bounce', 'signup-42'),
  subject: 'Bounce handling test',
  html: '<p>Simulated.</p>',
})
```

Mail to the simulator never leaves Groundmail. Sends to it are test sends (`"test": true`), with everything that means above. They also never touch:

- your suppression list (`bounce@` and `complaint@` are not added to it, and `suppressed@` is refused without being on it),
- the shared list of addresses that hard-bounced, which [Groundmail validation](https://docs.groundmail.dev/validation) uses,
- your bounce and complaint rates.

With a live key, a send must go either to simulator addresses only or to real recipients only; mixing them returns a 400 `validation_error`. With a test key you can mix them, since nothing is delivered either way. When one email has several simulator recipients, it takes the most severe outcome: bounce, then block, then complaint, then delayed, then delivered.

## Testing webhooks

Point a [webhook](https://docs.groundmail.dev/webhooks) at your handler, then send to simulator addresses to get each event with a real payload and a real signature. For example, a simulated hard bounce:

```json
{
  "type": "email.bounced",
  "created_at": "2026-10-18T12:00:00.000Z",
  "data": {
    "email_id": "msg_…",
    "to": ["bounce+signup-42@simulator.groundmail.dev"],
    "from": "you@yourdomain.com",
    "subject": "Bounce handling test",
    "status": "bounced",
    "bounce_reason": "550 5.1.1 <bounce+signup-42@simulator.groundmail.dev>: Recipient address rejected: User unknown (simulated hard bounce)",
    "bounce_type": "hard",
    "tags": [],
    "test": true
  }
}
```

`data.test` is `true` on every simulated event and absent on events from real mail, so your handler can skip side effects for tests. To send one event to one endpoint without an email, use `POST /emails/test` (its events are marked `test` too).
