Markdown

Testing

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

Updated Nov 17, 20265 min read

  • 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 page (in Test mode, or tick Test key), or through the API:

Terminal
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}'
Terminal
groundmail keys create --name CI --scopes emails:send,emails:read --test
TypeScript
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 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, 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: 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. 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 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.

Terminal
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>"
  }'
TypeScript
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 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 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).

Was this page helpful?