Skip to content

Test Mode

Test your integration without sending real emails. Test mode API keys simulate the full email pipeline -- validation, queueing, and events -- without delivering anything.

Test API Keys

Test mode is activated by using an API key that starts with sk_test_ instead of sk_live_. Create test keys from the dashboard under Configuration → API keys.

typescript
import { PostStack } from '@poststack.dev/sdk';

// Use a test key -- no real emails will be sent
const poststack = new PostStack('sk_test_...');

// This email is validated and queued, but never delivered
const { id } = await poststack.emails.send({
  from: 'you@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Test Email',
  html: '<p>This is a test.</p>',
});

// id is still returned, and events are simulated

How Test Mode Works

Test mode behaves identically to live mode with these differences:

No actual delivery

Emails are validated and queued but never sent to the recipient's mail server. No SMTP connection is made.

Simulated events

PostStack automatically generates simulated delivery events (queued, sent, delivered) so you can test your webhook handlers and event processing.

Full validation

All request validation is applied -- domain verification checks, schema validation, permission checks, and rate limits all work normally.

No billing impact

Test emails are not counted toward your usage quota and do not incur any charges.

Test Mode with cURL

Simply use your test API key in the Authorization header:

bash
curl -X POST https://api.poststack.dev/emails \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Test Email",
    "html": "<p>This is a test.</p>"
  }'

Testing Webhooks

Test mode emails still trigger webhook deliveries with simulated events. This makes it easy to develop and test your webhook handler end-to-end:

typescript
// 1. Create a webhook (works with both test and live keys)
await poststack.webhooks.create({
  url: 'https://yourdomain.com/webhooks/poststack',
  events: ['email.delivered', 'email.bounced'],
});

// 2. Send a test email
await poststack.emails.send({
  from: 'you@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Test',
  html: '<p>Testing webhooks</p>',
});

// 3. Your webhook endpoint receives simulated events:
// - email.sent
// - email.delivered

Identifying Test Emails

Mode lives on the API key, not the email record — there is no test_mode field on email responses. To separate test traffic from production traffic, use a dedicated sk_test_ key per environment and filter on tags or domain_id when listing emails.

Test sends are excluded from billing usage — they never consume a send from your plan's monthly allowance. They are not excluded from analytics: a test send is recorded as a normal delivered email, so it appears in the emails list and counts towards the dashboard's sent/delivered/bounced totals, the timeseries, and the provider and geography breakdowns. If your test volume is large enough to distort those numbers, tag every test send (or route it through a dedicated test domain) and filter accordingly.

typescript
// Tag every test send so you can filter it out later
await poststack.emails.send({
  from: 'you@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Test Email',
  html: '<p>This is a test.</p>',
  tags: ['env:test'],
});

// Filter just your test sends:
const { data } = await poststack.emails.list({ tag: 'env:test' });