# messagebird.dev - test email delivery, bounces & complaints

A mail sandbox for the Bird Email API. Send to any of these addresses through the API and Bird intercepts the message, skips the real send, and synthesizes exactly the delivery event you asked for. You get the full flow - the dashboard, webhooks, and the API, end to end - without a real inbox in sight and without ever touching your domain's sending reputation.

## Test addresses

Every outcome the pipeline can produce has an address. Pick one and send to it:

| Address                                        | Simulates                                                                                                                   |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `delivered@messagebird.dev`                    | A clean delivery. Emits `processed` then `delivered`.                                                                       |
| `bounce@messagebird.dev` (alias `hardbounce@`) | A hard bounce - `550 5.1.1 Unknown User`. Permanent; the address is a candidate for suppression.                            |
| `softbounce@messagebird.dev`                   | A soft bounce - `451 4.3.0 Temporary failure, please retry`. Transient, the kind a sender retries.                          |
| `complaint@messagebird.dev` (alias `spam@`)    | A spam / abuse complaint (feedback loop), as if the recipient hit "report spam".                                            |
| `suppressed@messagebird.dev`                   | Short-circuits before the send - the message never reaches the sender. Models a recipient already on your suppression list. |
| `reject@messagebird.dev`                       | A transmission rejection - the provider refuses the message outright. No delivery events follow.                            |
| `deferred@messagebird.dev` (alias `delay@`)    | A temporary deferral - `451 4.2.1 Mailbox temporarily unavailable, will retry`.                                             |

```sh
# Send through the Bird Email API (use your region's host) - the recipient decides the outcome.
curl https://eu1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@your-domain.com",
    "to": ["bounce@messagebird.dev"],
    "subject": "Bounce me",
    "text": "This one never lands."
  }'

# Watch the synthesized processed -> bounced events arrive on your webhook.
```

## How to test a delivered email

Send to `delivered@messagebird.dev` for a clean, successful delivery. Bird emits a `processed` event followed by `delivered` - the happy path, end to end, so you can confirm your webhook and dashboard light up the way they should.

## How to test a bounced email

Send to `bounce@messagebird.dev` (or `hardbounce@messagebird.dev`) to simulate a permanent hard bounce. Bird returns `550 5.1.1 Unknown User` and the recipient becomes a suppression candidate, exactly as a dead address would on a real send.

## How to test a soft bounce

Send to `softbounce@messagebird.dev` for a transient failure - `451 4.3.0 Temporary failure, please retry`. This is the retryable kind of bounce, so you can exercise your retry and back-off handling without burning a real recipient.

## How to test a spam complaint

Send to `complaint@messagebird.dev` (or `spam@messagebird.dev`) to fire a spam / abuse complaint through the feedback loop - as if the recipient had hit "report spam". Use it to verify you honor complaints and pull those recipients from future sends.

## How to test a suppressed recipient

Send to `suppressed@messagebird.dev` to model a recipient already on your suppression list. The message short-circuits before the send and never reaches the provider - the right outcome to assert when you expect suppression to stop a message cold.

## How to test a rejected email

Send to `reject@messagebird.dev` to have the provider refuse the message outright. No delivery events follow - the send is rejected at hand-off, so you can test how your code surfaces an outright transmission failure.

## How to test a deferred email

Send to `deferred@messagebird.dev` (or `delay@messagebird.dev`) for a temporary deferral - `451 4.2.1 Mailbox temporarily unavailable, will retry`. Bird re-attempts delivery, so you can watch a delayed message move through your webhook and dashboard.

## How it works

Detection is by domain and local-part alone - no real mailbox, suppression entry, or verification state is involved, so a simulator address behaves the same in every environment.

Matching is case-insensitive, and `+label` subaddressing is stripped before matching - so `bounce+signup-flow@messagebird.dev` is still a hard bounce, which lets you tag a simulated send without changing the outcome. Anything else on the domain (say `noreply@messagebird.dev`) isn't a simulator address and is treated like any other recipient.

---

- Bird docs: https://docs.bird.com
- bird.com: https://bird.com