Skip to main content

Test Mode

Test mode lets you develop and test your Zyphr integration without sending real notifications to users. Messages are stored and can be inspected, but are never delivered to actual recipients.

How Test Mode Works​

When you use a zy_test_* API key:

  1. Messages are stored - All messages are saved to the database
  2. No delivery - Messages skip the actual delivery providers (SES, FCM, Twilio)
  3. Mock responses - You receive realistic API responses
  4. Events are tracked - Status changes and events are recorded
  5. Dashboard visibility - View test messages in the dashboard

Using Test Mode​

Create a Test API Key​

  1. Go to Settings → API Keys
  2. Click Create API Key
  3. Select Test as the key type
  4. Copy your zy_test_* key

Send Test Messages​

Use your test key in API requests:

curl -X POST https://api.zyphr.dev/v1/emails \
  -H "X-API-Key: zy_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "anyone@example.com",
    "subject": "Test Email",
    "html": "<p>This won'\''t actually be delivered!</p>"
  }'

Response includes is_test: true:

{
  "data": {
    "id": "msg_test123",
    "to": "anyone@example.com",
    "status": "sent",
    "is_test": true,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

What Happens to Test Messages​

Email​

  • Stored in database with is_test = true
  • Status progresses: queued → sending → sent
  • No email is sent via SES
  • Mock message ID: test_mock_<message_id>

Push Notifications​

  • Stored with is_test = true
  • Status: queued → sending → sent
  • No push sent via FCM/APNs
  • Mock message ID generated

SMS​

  • Stored with is_test = true
  • Status: queued → sending → sent
  • No SMS sent via Twilio
  • Mock segment count: 1

In-App Notifications​

  • Created normally in the inbox
  • Visible to subscribers if they exist
  • Marked with is_test = true

Identifying Test Messages​

In API Responses​

All responses include the is_test flag:

{
  "data": {
    "id": "msg_123",
    "is_test": true
  }
}

In the Dashboard​

Test messages are clearly labeled in the dashboard with a "Test" badge. You can filter to show only test or only live messages.

In the Database​

Query test messages:

SELECT * FROM messages WHERE is_test = true;

Best Practices​

Use Test Keys in Development​

Set up your development environment to always use test keys:

.env.development
ZYPHR_API_KEY=zy_test_development_key
.env.production
ZYPHR_API_KEY=zy_live_production_key

Test All Channels​

Verify your integration works for all channels you plan to use:

// Test email
await zyphr.emails.send({
  to: 'test@example.com',
  subject: 'Test',
  html: '<p>Test</p>'
});

// Test push
await zyphr.push.send({
  userId: 'test_user',
  title: 'Test Push',
  body: 'Test notification'
});

// Test SMS
await zyphr.sms.send({
  to: '+14155551234',
  body: 'Test SMS'
});

Verify Webhook Handling​

Test webhooks work the same in test mode. Configure a webhook endpoint and verify you receive events:

{
  "event": "message.sent",
  "data": {
    "message_id": "msg_test123",
    "is_test": true
  }
}

Automatic Cleanup​

Test data is automatically cleaned up after 30 days to keep your workspace tidy. If you need longer retention for testing, contact support.

Switching to Production​

When you're ready to go live:

  1. Verify your domain (required for email)
  2. Configure push credentials (FCM, APNs)
  3. Configure SMS credentials (Twilio)
  4. Swap your test key for a live key
  5. Test with a single real recipient first
- ZYPHR_API_KEY=zy_test_your_key
+ ZYPHR_API_KEY=zy_live_your_key

FAQ​

Can I mix test and live keys?​

Each API request uses exactly one key. You cannot mix test and live operations in a single request.

Do test messages count against my quota?​

Test messages do not count against your monthly message quota.

Can I test webhooks?​

Yes! Webhooks fire for test messages just like live messages. The webhook payload includes is_test: true.

How do I clean up old test data?​

Test data older than 30 days is automatically deleted. For immediate cleanup, contact support.