Test mode and sandbox

Two things let you build without touching an inbox: test keys, which never send, and the sandbox domain with its simulator addresses, which work in both modes.

Test keys

Keys that start with av_test_ run the whole pipeline: validation, sender rules, the event log and webhooks. The only thing that does not happen is the send itself, and with it the suppression check: your suppression list is made of real recipients' bounces and complaints, and a test send never reaches anyone. About two seconds after a test send is accepted, the email is marked sent and then delivered, or bounced for the bounce simulator. The complaint simulator is delivered first and then marked complained, the same order a real complaint arrives in. Your webhooks receive the same payloads they would in live mode, with "mode": "test".

curl -X POST https://api.avelto.dev/v1/emails \  -H "Authorization: Bearer av_test_..." \  -H "Content-Type: application/json" \  -d '{    "from": "Acme <hello@mail.acme.com>",    "to": "jane@example.com",    "subject": "Password reset",    "text": "Nothing is sent. The events and webhooks still fire."  }'

Test emails are free, do not count towards your monthly limit, and show up in the dashboard and in GET /v1/emails with mode: "test".

A test key only ever sees test data

The mode is a boundary, not a filter on a shared pile. A test key reads test emails and nothing else:

• GET /v1/emails returns test emails. ?mode=live does not change that.
• GET /v1/emails/:id returns 404 for a live email, as do its events and its webhook deliveries. It is the same 404 you get for an id that does not exist.
• Idempotency keys are kept per mode. A test send that reuses a live send's key creates a test email rather than replaying the live one, and the other way round.
• Anything live sending depends on needs a live key, because it has no mode of its own: removing a domain, creating, changing, deleting or restoring a template, creating, changing or deleting a webhook endpoint, reading or changing the suppression list, changing the account settings, GET /v1/account/export and POST /v1/recipients/erase. These return 403 live_key_required with a message saying so.
• A test key that may manage keys creates test keys only.

A test key can still add and read domains (a new domain changes nothing until you publish its DNS records), read templates and webhook endpoints, send with a template in test mode, and list and retry the deliveries of test events. It cannot read the suppression list, and POST /v1/emails/validate does not check an address against it for a test key: the list is made of real recipients' addresses.

A live key reads both modes: it defaults to live, and ?mode=test shows test emails.

The practical upshot is that a test key is safe to put somewhere a live key is not: CI, a shared staging environment, a colleague's machine. Losing one costs you nothing but the key.

The sandbox domain

Every account can send from sandbox.avelto.dev before it has verified a domain. Any local part works, so you@{site.sandboxDomain} is a valid from. Two rules apply:

• Sends to the simulator addresses below are always allowed.
• Sends to anyone else are allowed only when every other recipient across to, cc and bcc is your account's owner email, and that email is verified. Simulator addresses can be mixed in.

Anything else returns 403 sandbox_recipient_not_allowed:

{  "error": {    "code": "sandbox_recipient_not_allowed",    "message": "The sandbox sender @sandbox.avelto.dev only delivers to the account owner (you@example.com). Verify a domain to send to anyone.",    "details": { "recipients_not_allowed": ["jane@example.com"] }  }}

Verify a domain to send to anyone.

Simulator recipients

Three addresses on the sandbox domain produce a fixed outcome. They work with live keys as well as test keys, and they never add anything to your suppression list.

curl -X POST https://api.avelto.dev/v1/emails \  -H "Authorization: Bearer av_live_..." \  -H "Content-Type: application/json" \  -d '{    "from": "you@sandbox.avelto.dev",    "to": "bounced@sandbox.avelto.dev",    "subject": "Bounce test",    "text": "This one bounces."  }'

Use them to exercise your webhook handler for every path before real traffic arrives.

What test mode does not cover

• Rendering in a real mail client. Send a live email to your own account address from the sandbox domain for that.
• Provider throttling or deferrals. Test sends always complete in about two seconds.
• The suppression list. To see a recipient_suppressed refusal, send live from the sandbox domain to your own address after suppressing it.