Skip to main content

Test mode

Test mode validates the send and simulates its outcome without delivering it to a mail server. It does not consume sending quota or affect your sending reputation.

There are two ways in, and they compose.

Test keys​

A key created in the test environment is prefixed tix_test_ and can never send real mail. Use it in CI, in local development, and anywhere you would rather not hand out a credential that can reach your customers.

Authorization: Bearer tix_test_...

For email sending and reads:

  • Sends are simulated. No message leaves the platform.
  • Nothing counts against your daily or monthly send allowance.
  • Email reads are separated by environment. Listing returns test messages; fetching a live message with a test key returns not_found, so a leaked test key cannot read production mail.
  • It can only create further test keys. Asking for a live key returns test_mode_restricted.
  • It has its own rate-limit allowance, so a load test cannot starve production.

This isolation applies to email records, not a separate copy of every workspace resource. Domains, templates and other management resources remain scoped to the workspace. Inbound mail and broadcast send/test operations require a live key.

Sending validation still applies. An unverified sending domain still fails, a malformed from still fails, an oversized attachment still fails. That is the point: test mode is useful precisely because it does not skip validation.

Sandbox addresses​

Recipients at epostix.dev select a simulated outcome with the local part. If any to, cc or bcc address is a sandbox recipient, the whole send is simulated, including its other recipients. Keep sandbox recipients separate from live sends.

RecipientWhat happens
[email protected]Accepted and delivered
[email protected]Rejected as a hard bounce: the mailbox does not exist
[email protected]Delivered, then marked as spam
[email protected]Blocked before sending
[email protected]Deferred because the mailbox is full, then delivered

Each accepts a +label suffix, so [email protected] and [email protected] are distinct messages. Use labels in loops: without them you will trip duplicate detection on the eleventh identical send inside a minute.

Any other local part at that domain is rejected with a validation_error listing the ones that work, rather than quietly defaulting to delivered.

Sandbox addresses work with live keys too. A live key sending to [email protected] produces a simulated bounce: no delivery, no quota, no effect on reputation, and no suppression written to your account. That is how you exercise your bounce handling against your real production credentials.

Webhooks fire either way​

Simulated sends emit delivery events with the same envelope and the same fields as live sends, so your handler can exercise its bounce path without sending real mail. Every simulated event adds simulated: true and outcome, the local part of the sandbox address. Do not rely on webhook arrival order: delivery retries can change it.

RecipientEvents
[email protected]email.delivered
[email protected]email.bounced, then email.failed
[email protected]email.delivered, then email.complained
[email protected]email.failed
[email protected]email.delayed, then email.delivered

[email protected] produces a recipient fault with a fixed reply:

{
"email_id": "...",
"domain_id": "...",
"simulated": true,
"outcome": "bounced",
"fault": "recipient",
"reason": "mailbox_unknown",
"permanent": true,
"source": "smtp",
"smtp_code": 550,
"enhanced_status_code": "5.1.1",
"response": "550 5.1.1 user unknown"
}

The email.failed that follows carries the same verdict as its bounce, and a failure of bounced with a recipient fault. [email protected] produces email.failed with a failure of suppressed and a recipient fault, as an address suppressed for bouncing would.

[email protected] produces email.delayed with a bounce of recipient, mailbox_full, permanent: false and 452 4.2.2 mailbox full. [email protected] produces email.complained with feedback_type abuse and provider other. See webhook events for what each field means.

This is the reason to use sandbox addresses rather than mocking our API: you are testing your own webhook handler against real deliveries of real payloads.

Telling them apart afterwards​

Every message carries a mode field, either live or test, so a simulated send is identifiable long after it was made.

{
"id": "...",
"mode": "test",
"status": "delivered"
}

What test mode does not cover​

SMTP submission is always live. SMTP credentials have no test variant, so a message sent through smtp.epostix.com is a real send whatever else you have configured. Use the API when you want a simulated send.