Testing

Never test with made-up addresses at real domains: they bounce and hurt your sender reputation. SpacePost provides test inboxes at test.spacepost.dev. Mail to them is never delivered anywhere, but the full event pipeline runs, including webhooks.

Address	Simulates	Events you will see
delivered@test.spacepost.dev	Successful delivery	email.sent, email.delivered
bounced@test.spacepost.dev	Hard bounce (permanent)	email.sent, email.bounced
complained@test.spacepost.dev	Recipient marks as spam	email.sent, email.delivered, email.complained
delayed@test.spacepost.dev	Temporary delivery problem	email.sent, email.delivery_delayed
softbounced@test.spacepost.dev	Soft bounce (mailbox full); the third within 30 days suppresses the address	email.sent, email.delivery_delayed

Labels

Add +label to run multiple scenarios in parallel and tell them apart: delivered+signup@test.spacepost.dev, bounced+case-17@test.spacepost.dev. The label is ignored when choosing the outcome.

Caution

Simulated hard bounces and complaints behave like real ones: the address is added to your suppression list and counts toward automatic pausing thresholds. Delete test entries from Suppressions in the dashboard, or with DELETE /suppressions/{email}, after running a bounce test.

The test sender

Before you verify a domain you can send from onboarding@test.spacepost.dev. It is restricted:

• it can send only to your own team members’ email addresses and to @test.spacepost.dev addresses;
• any other recipient is rejected with 403 validation_error;
• once your domain is verified, send from your own address.

Node.js

test.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

await spacepost.emails.send({
  from: "Acme <onboarding@test.spacepost.dev>",
  to: ["delivered@test.spacepost.dev", "bounced+case-1@test.spacepost.dev"],
  subject: "Test",
  html: "<p>Test</p>",
});

cURL

curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <onboarding@test.spacepost.dev>",
    "to": ["delivered@test.spacepost.dev"],
    "subject": "Test",
    "html": "<p>Test</p>"
  }'

Testing your webhook handler

1. Create a webhook that points at a tunnel to your machine (for example https://abc123.ngrok.app/webhooks/spacepost), subscribed to the events you handle.
2. Send to delivered@, bounced@, complained@ and delayed@.
3. Check that your handler verifies the signature and responds 2xx.

Test sends count toward your monthly quota like any other email.