A webhook handler needs tests for failed delivery as well as success. A test that stops at the send response cannot confirm how your application handles the later event.
Magic destinations let you exercise those outcomes without reaching a real inbox or handset. Request validation still applies, so they also expose malformed sends.
How do I send a test request?
Send to a recognized magic destination using your normal API credentials and endpoint.
There is no test mode to enable. For email, use a documented address on messagebird.dev. For SMS, use one of the numbers below.
Simulated recipients follow the normal event and signed-webhook paths. They do not exercise delivery to external infrastructure. They therefore cannot verify real inbox placement or handset rendering.
Use only recognized magic destinations when a test must not contact anyone. A request can mix simulated and real recipients. Real recipients are delivered normally.
Which email addresses should I use?
Use delivered@messagebird.dev to test acceptance by the receiving server. The other addresses below exercise bounce, complaint and rejection handling.
| Address | Outcome |
|---|---|
delivered@messagebird.dev | The receiving server accepts the message. |
bounce@messagebird.dev or hardbounce@messagebird.dev | A hard bounce with SMTP 550; test permanent-failure handling. |
softbounce@messagebird.dev | A soft bounce with SMTP 451; test temporary-failure classification. |
deferred@messagebird.dev or delay@messagebird.dev | A deferral with no subsequent simulated retry. |
complaint@messagebird.dev or spam@messagebird.dev | A spam complaint. |
suppressed@messagebird.dev | Rejection as an already-suppressed recipient, with no processing or delivery events. |
reject@messagebird.dev | Rejection before a delivery attempt. |
Matching ignores case. It strips +label before selecting the outcome. For example, bounce+signup-flow@messagebird.dev still bounces. The full address remains in events so you can associate them with that test.
Only the documented names on that domain are magic. bounce@yourdomain.com is a normal recipient, as is an unrecognized name on messagebird.dev.
Simulated bounces and complaints do not add addresses to Bird's suppression list or affect sending reputation. Your application still receives their events, so check how your own suppression logic handles them.
Test email delivery lists the complete event sequences and matching rules.
Which phone numbers should I use?
Use +15005550006 to test successful SMS delivery. The other numbers below exercise rejection and failure paths.
| Destination | Outcome |
|---|---|
+15005550001 | Submission rejection with invalid_destination. |
+15005550002 | sms.sent, then sms.undelivered with unreachable. |
+15005550003 | sms.sent, then sms.failed with provider_unavailable. |
+15005550004 | sms.sent, then sms.failed with blocked_by_carrier. |
+15005550006 | sms.sent, then sms.delivered. |
+15005550009 | sms.sent, then sms.failed with recipient_opted_out. |
Enable the United States under Destinations. Use a from sender valid for the US. An alphanumeric sender is rejected there, so it cannot test these numbers successfully.
A send to +15005550006 can test your success handler. Use +15005550002 to check the separate undelivered path. The SMS migration guide includes a smoke-test sequence.
What does testing cost or change?
Simulated sends use real allowances and can affect your statistics.
An SMS to a magic number is billed at the destination's normal rate. Limit repeated tests because every simulated send can incur a charge.
A simulated email recipient counts against your send allowance. Email sandbox traffic also enters aggregate statistics, including bounce and complaint rates. Separate it in your analysis so test failures do not look like customer delivery problems.
How do I identify a test result?
Match the event to the test recipient or message identifier you recorded when sending.
An accepted simulated email returns 202 and normal event shapes. There is no test flag in the payload. Acceptance alone therefore does not identify a test.
Use a recipient label such as bounce+signup-flow@messagebird.dev to associate email events with a run. You can also read the email message's timeline or events API without operating a webhook receiver.
Keep a real-delivery check separate when you need to verify rendering or receipt. Magic destinations do not test those parts of the delivery path.
In short
The destination selects the test outcome.
Use your normal API key and endpoints. Recognized addresses and numbers trigger simulated delivery results.
Limit tests to known magic destinations.
A request can mix simulated and real recipients. Unrecognized addresses are handled as normal recipients.
Testing still uses real allowances.
Simulated email recipients use send allowance. SMS magic numbers are billed at the destination's normal rate.
Record which messages belong to a test.
Events have no test flag. Email labels remain in recipient addresses, letting you identify a test run in its events.