E-mailbezorging testen (mail-sandbox)

Met de mail-sandbox test je webhookhandlers, suppressielogica en bezorgresultaten zonder naar een echte inbox te verzenden. Verzend via de normale API naar een adres op messagebird.dev. Het lokale deel bepaalt het resultaat: bounce@messagebird.dev bouncet en delivered@messagebird.dev wordt bezorgd.

Een sandboxverzending doorloopt de normale paden voor acceptatie, events en webhooks. Je krijgt hetzelfde 202-antwoord en dezelfde payloadstructuur per ontvanger voor events als bij een productieverzending. De payload bevat geen testvlag. Het bericht bereikt geen externe bezorginfrastructuur en geen echte inbox. Gesimuleerde bounces en klachten hebben geen invloed op je verzendreputatie en worden niet naar de suppressielijst geschreven, dus je kunt de adressen opnieuw gebruiken.

De sandbox vraagt geen configuratie: geen schakelaar, geen testmodus en geen speciale API-sleutel. Hij wordt uitsluitend geactiveerd door het ontvangeradres, op de normale verzendendpoints (POST /v1/email/messages en POST /v1/email/batches) en bij een broadcast. Een contact in de doelgroep met een sandboxadres wordt gesimuleerd in plaats van gemaild. Zo oefen je een campagne zonder iemand te mailen. Een gesimuleerde ontvanger telt wel mee voor je verzendtegoed, dus de oefening gebruikt hetzelfde quotum als de echte verzending.

Magische adressen

Alle adressen staan op @messagebird.dev. Het lokale deel bepaalt het resultaat:

De reeksen hierboven zijn de webhooks die één losse verzending oplevert. Laat bij een broadcast de eerste email.accepted weg: een broadcastontvanger wordt zelfstandig geaccepteerd, maar we registreren dat event zonder er een webhook voor te sturen. Elke reeks begint dus bij wat daarna volgt: email.processed op de afleverpaden en email.rejected voor suppressed@ en reject@. Alles daarna is identiek, en de eventreferentie beschrijft de regel volledig.

Een verzending kan sandbox- en echte ontvangers combineren. Elke ontvanger krijgt een eigen levenscyclus: echte ontvangers krijgen het bericht gewoon afgeleverd, sandboxontvangers worden gesimuleerd.

Dezelfde events verschijnen ook op de tijdlijn van het bericht in het e-maillogboek en in de events-API. Zo kun je de sandbox gebruiken zonder webhookendpoint en de uitkomsten daarna teruglezen.

Adresseringsregels

• Herkenning gebeurt alleen op het lokale deel, en alleen op het domein messagebird.dev. bounce@yourdomain.com is een normaal adres.
• Alleen de lokale delen in de tabel met magische adressen zijn magisch. Elk ander adres op messagebird.dev is een normale ontvanger. Als je verstuurt vanaf het gedeelde onboardingdomein, moet dat adres van een geverifieerd lid van de werkruimte zijn.
• Matching is niet hoofdlettergevoelig: Bounce@messagebird.dev en bounce@messagebird.dev gedragen zich identiek.
• +label-subadressering wordt vóór het matchen verwijderd: bounce+signup-flow@messagebird.dev bouncet nog steeds. Gebruik labels om testgevallen te koppelen. Het volledige adres, inclusief label, verschijnt in je events en webhooks, zodat elke testrun zijn eigen ontvangers kan markeren.

Stapsgewijs: een bounce simuleren, van begin tot eind

Je hebt geen geverifieerd verzenddomein nodig. Verstuur vanaf onboarding@messagebird.dev, zoals beschreven in Je eerste e-mail versturen. Herkende sandboxadressen vallen niet onder de beperking van het onboardingdomein tot geverifieerde leden, maar tellen wel mee voor het dagelijkse quotum.

Zorg dat je een webhook-endpoint hebt dat geabonneerd is op e-mailevents (zie Webhooks) en verstuur dan:

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["bounce+signup-flow@messagebird.dev"],
  subject: "Sandbox bounce test",
  html: "<p>This message will hard-bounce.</p>",
  tags: [{ name: "flow", value: "signup" }],
  metadata: { test_run: "docs-capture-1" },
});
console.log(msg.id, msg.status); // "em_…", "accepted"

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["bounce+signup-flow@messagebird.dev"],
    subject="Sandbox bounce test",
    html="<p>This message will hard-bounce.</p>",
    tags=[{"name": "flow", "value": "signup"}],
    metadata={"test_run": "docs-capture-1"},
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
		From:     "onboarding@messagebird.dev",
		To:       []string{"bounce+signup-flow@messagebird.dev"},
		Subject:  "Sandbox bounce test",
		HTML:     "<p>This message will hard-bounce.</p>",
		Tags:     []bird.Tag{{Name: "flow", Value: "signup"}},
		Metadata: map[string]any{"test_run": "docs-capture-1"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['bounce+signup-flow@messagebird.dev'],
    subject: 'Sandbox bounce test',
    html: '<p>This message will hard-bounce.</p>',
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --from onboarding@messagebird.dev \
  --html '<p>This message will hard-bounce.</p>' \
  --metadata '{"test_run":"docs-capture-1"}' \
  --subject 'Sandbox bounce test' \
  --tag flow=signup \
  --to bounce+signup-flow@messagebird.dev

curl -X POST "https://us1.platform.bird.com/v1/email/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "onboarding@messagebird.dev",
    "to": ["bounce+signup-flow@messagebird.dev"],
    "subject": "Sandbox bounce test",
    "html": "<p>This message will hard-bounce.</p>",
    "tags": [{ "name": "flow", "value": "signup" }],
    "metadata": { "test_run": "docs-capture-1" }
  }'

Begint je sleutel met bk_eu1_, roep dan https://eu1.platform.bird.com aan.

De API antwoordt met 202 Accepted en een em_*-bericht-ID, niet te onderscheiden van een productieverzending. Zo test je precies je echte codepad. Je webhook-endpoint ontvangt daarna email.accepted, email.processed en ten slotte email.bounced. Elk event bevat de tags en metadata van de verzending (null als de verzending die niet had), en de payload van email.bounced bevat de volledige bounceclassificatie:

{
  "type": "email.bounced",
  "timestamp": "2026-07-23T14:51:00.362Z",
  "data": {
    "email_id": "em_01ky7qanhrejer0bn34v38hrxh",
    "recipient_id": "er_01ky7qanhrejds4decpk83q5qq",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
    "recipient": "bounce+signup-flow@messagebird.dev",
    "recipient_role": "to",
    "bounce_type": "hard",
    "bounce_class": 10,
    "bounce_code": "550",
    "bounce_description": "5.1.1 Unknown User",
    "sending_ip": null,
    "tags": [{ "name": "flow", "value": "signup" }],
    "metadata": { "test_run": "docs-capture-1" },
    "broadcast_id": null
  }
}

De betekenis van de velden staat in de eventsreferentie. Nergens in de payload staat een simulatorvlag: het eventtype en de vorm zijn precies wat een echte hard bounce oplevert. Alleen het ontvangersadres zelf laat zien dat het om een simulatie gaat. Moet je handler testverkeer apart behandelen, baseer dat dan op het ontvangersdomein messagebird.dev.

Wil je controleren dat er nooit naar een al onderdrukte ontvanger wordt verzonden, herhaal de verzending dan met suppressed@messagebird.dev. Controleer dat je email.accepted ontvangt en daarna email.rejected met rejection_reason: "recipient_suppressed". Je hoort geen email.processed of afleveringsevents te ontvangen. Dit gedraagt zich precies als een echte onderdrukte ontvanger: het bericht wordt geaccepteerd en tijdens de verwerking afgebroken, nog vóór er iets wordt verzonden.

Wat de sandbox wel en niet doet

• Geen schrijfacties naar de suppressielijst. Gesimuleerde hard bounces en klachten voegen de ontvanger niet toe aan je suppressielijst; daardoor blijven de adressen herbruikbaar. Je webhook wordt nog steeds aangeroepen (email.bounced, email.complained), zodat je eigen suppressielogica volledig wordt getest. Gebruik het speciale adres suppressed@ om het afwijzingspad voor al onderdrukte ontvangers te testen.
• Nooit echte aflevering. Sandboxontvangers worden onderschept voordat het bericht de afleveringsinfrastructuur bereikt. Er wordt niets verzonden, er is geen inbox bij betrokken en je verzendreputatie blijft onaangetast.
• Validatie van verzoeken blijft gelden. Een sandboxverzending gebruikt de normale endpoints, dus schemacontroles, groottelimieten en headerregels wijzen een ongeldig verzoek zoals gewoonlijk af. De sandbox slaat alles na de overdracht over: rendering en afleveringsgedrag voorbij dat punt worden niet getest.
• Opens en klikken worden niet gesimuleerd. Een magisch adres simuleert het verzendresultaat en niemand opent het bericht, dus email.opened en email.clicked komen alleen van echte e-mail.
• Statistieken bevatten sandboxverkeer. Sandboxverzendingen tellen mee in de totale statistieken van je werkruimte en in je bounce- en klachtpercentages. Veel sandboxbounces vertekenen je dashboards, terwijl je reputatie ongewijzigd blijft.

Volgende stappen

• Events: alle eventtypen en de levenscyclus per ontvanger
• Webhooks: abonneren, handtekeningverificatie en opnieuw proberen
• Je eerste e-mail verzenden: de snelstartgids voor het onboardingdomein waarop deze walkthrough voortbouwt
• Suppressies: hoe de echte suppressielijst werkt
• E-mail testen zonder iemand te spammen: een video die de sandboxadressen doorloopt en laat zien welke events elk adres oplevert