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.
| Recipient | What 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.
| Recipient | Events |
|---|---|
[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.