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 Settings → 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.queued
// - email.sent
// - email.delivered

Identifying Test Emails

Test emails and events include a test_mode: true flag so you can distinguish them in your code:

json
{
  "id": "em_test_abc123def456",
  "from": "you@yourdomain.com",
  "to": ["user@example.com"],
  "subject": "Test Email",
  "status": "delivered",
  "test_mode": true,
  "created_at": "2026-03-23T10:00:00.000Z"
}