E-Mail-Zustellung testen (Mail-Sandbox)

Mit der Mail-Sandbox testen Sie Webhook-Handler, Unterdrückungslogik und Zustellergebnisse, ohne an ein echtes Postfach zu senden. Senden Sie über den normalen API an eine Adresse unter messagebird.dev. Der lokale Teil bestimmt das Ergebnis: bounce@messagebird.dev erzeugt einen Bounce, delivered@messagebird.dev wird zugestellt.

Ein Sandbox-Versand nutzt die normalen Pfade für Annahme, Events und Webhooks. Er liefert dieselbe 202-Antwort und erzeugt pro Empfänger dieselben Payload-Strukturen für Events wie ein Produktivversand. Die Payload enthält kein Test-Flag. Die Nachricht erreicht weder die externe Zustellinfrastruktur noch ein echtes Postfach. Simulierte Bounces und Beschwerden beeinflussen die Absenderreputation nicht und werden nicht in die Unterdrückungsliste geschrieben, sodass Sie die Adressen wiederverwenden können.

Die Sandbox braucht keine Einrichtung: keinen Schalter, keinen Testmodus, keinen speziellen API-Schlüssel. Sie wird allein durch die Empfängeradresse ausgelöst, an den normalen Versand-Endpunkten (POST /v1/email/messages und POST /v1/email/batches) und bei einem Broadcast. Hat ein Kontakt in der Zielgruppe eine Sandbox-Adresse, wird der Versand an ihn simuliert statt ausgeführt. So proben Sie eine Kampagne, ohne jemandem eine E-Mail zu senden. Ein simulierter Empfänger zählt trotzdem gegen Ihr Versandkontingent, sodass die Probe dasselbe Kontingent beansprucht wie der echte Versand.

Magische Adressen

Alle Adressen liegen unter @messagebird.dev. Der lokale Teil wählt das Ergebnis aus:

Die obigen Abfolgen sind die Webhooks, die ein einzelner Versand erzeugt. Bei einem Broadcast entfällt das einleitende email.accepted: Ein Broadcast-Empfänger wird zwar eigenständig angenommen, wir erfassen dieses Ereignis aber, ohne dafür einen Webhook zu senden. Jede Abfolge beginnt daher mit dem nächsten Ereignis, also mit email.processed auf den Zustellungspfaden und mit email.rejected bei suppressed@ und reject@. Alles Weitere ist identisch, und die Ereignisreferenz beschreibt die Regel vollständig.

Ein Versand kann Sandbox- und echte Empfänger mischen. Jeder Empfänger durchläuft seinen eigenen Lebenszyklus: Echte Empfänger werden normal beliefert, Sandbox-Empfänger werden simuliert.

Dieselben Ereignisse erscheinen auch in der Zeitleiste der Nachricht im E-Mail-Log und in der Ereignis-API. So können Sie die Sandbox auch ohne Webhook-Endpunkt nutzen und die Ergebnisse dort auslesen.

Adressierungsregeln

• Die Erkennung erfolgt nur über den lokalen Teil und nur auf der Domain messagebird.dev. bounce@yourdomain.com ist eine normale Adresse.
• Nur die lokalen Teile in der Tabelle der magischen Adressen sind magisch. Jede andere Adresse unter messagebird.dev ist ein normaler Empfänger. Wenn Sie von der gemeinsamen Onboarding-Domain senden, muss diese Adresse einem verifizierten Workspace-Mitglied gehören.
• Groß- und Kleinschreibung spielt beim Abgleich keine Rolle: Bounce@messagebird.dev und bounce@messagebird.dev verhalten sich identisch.
• +label-Subadressierung wird vor dem Abgleich entfernt: bounce+signup-flow@messagebird.dev erzeugt trotzdem einen Bounce. Nutzen Sie Labels, um Testfälle zuzuordnen. Die vollständige Adresse samt Label erscheint in Ihren Ereignissen und Webhooks, sodass jeder Testlauf seine eigenen Empfänger kennzeichnen kann.

Schritt für Schritt: einen Bounce von Anfang bis Ende simulieren

Sie benötigen keine verifizierte Versanddomain. Senden Sie von onboarding@messagebird.dev, wie in Ihre erste E-Mail senden beschrieben. Erkannte Sandbox-Adressen sind von der Einschränkung der Onboarding-Domain auf verifizierte Mitglieder ausgenommen, zählen aber weiterhin zu ihrem Tageskontingent.

Stellen Sie sicher, dass Sie einen Webhook-Endpunkt haben, der E-Mail-Events abonniert (siehe Webhooks), und senden Sie dann:

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" }
  }'

Wenn Ihr Schlüssel mit bk_eu1_ beginnt, rufen Sie stattdessen https://eu1.platform.bird.com auf.

Der API antwortet mit 202 Accepted und einer em_*-Nachrichten-ID, nicht von einem Produktivversand zu unterscheiden. Genau darum geht es: Sie testen Ihren echten Codepfad. Ihr Webhook-Endpunkt empfängt anschließend email.accepted, email.processed und schließlich email.bounced. Jedes Event übernimmt tags und metadata des Versands (null, wenn der Versand keine hatte), und die email.bounced-Payload enthält die vollständige Bounce-Klassifizierung:

{
  "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
  }
}

Die Bedeutung der Felder finden Sie in der Events-Referenz. Die Payload enthält nirgends ein Simulator-Flag: Event-Typ und Struktur entsprechen genau einem echten Hard Bounce. Nur die Empfängeradresse selbst kennzeichnet ihn als simuliert. Wenn Ihr Handler Testverkehr gesondert behandeln muss, unterscheiden Sie anhand der Empfängerdomain messagebird.dev.

Um zu prüfen, dass an einen bereits unterdrückten Empfänger nie gesendet wird, wiederholen Sie den Versand mit suppressed@messagebird.dev. Prüfen Sie, dass Sie email.accepted und danach email.rejected mit rejection_reason: "recipient_suppressed" erhalten. Sie sollten kein email.processed und keine Zustell-Events erhalten. Das entspricht genau einem echten unterdrückten Empfänger: Die Nachricht wird angenommen und dann während der Verarbeitung vor jedem Versand abgebrochen.

Was die Sandbox tut und was nicht

• Keine Einträge in die Unterdrückungsliste. Simulierte Hard Bounces und Beschwerden fügen den Empfänger nicht Ihrer Unterdrückungsliste hinzu; deshalb bleiben die Adressen wiederverwendbar. Ihr Webhook wird trotzdem ausgelöst (email.bounced, email.complained), sodass Ihre eigene Unterdrückungslogik vollständig durchlaufen wird. Um den Ablehnungspfad für bereits unterdrückte Empfänger zu testen, verwenden Sie die dafür vorgesehene Adresse suppressed@.
• Niemals echte Zustellung. Sandbox-Empfänger werden abgefangen, bevor die Nachricht die Zustellinfrastruktur erreicht. Es wird nichts übertragen, kein Postfach ist beteiligt, und Ihre Versandreputation bleibt unberührt.
• Die Anfragevalidierung gilt weiterhin. Ein Sandbox-Versand nutzt die normalen Endpunkte, daher lehnen Schemaprüfungen, Größenlimits und Header-Regeln eine ungültige Anfrage wie gewohnt ab. Die Sandbox überspringt alles nach der Übergabe: Rendering und Zustellverhalten ab diesem Punkt werden nicht getestet.
• Öffnungen und Klicks werden nicht simuliert. Eine Magic-Adresse simuliert das Übertragungsergebnis, und niemand öffnet die Nachricht. Daher entstehen email.opened und email.clicked nur bei echten E-Mails.
• Statistiken enthalten Sandbox-Traffic. Sandbox-Sendungen fließen in die Gesamtstatistiken Ihres Workspace sowie in die Bounce- und Beschwerderaten ein. Viele Sandbox-Bounces verzerren Ihre Dashboards, ohne Ihre Reputation zu verändern.

Nächste Schritte

• Events: alle Event-Typen und der Lebenszyklus pro Empfänger
• Webhooks: Abonnieren, Signaturprüfung und erneute Versuche
• Ihre erste E-Mail senden: der Schnellstart mit der Onboarding-Domain, auf dem diese Anleitung aufbaut
• Unterdrückungen: wie die echte Unterdrückungsliste funktioniert
• E-Mails testen, ohne jemanden zuzuspammen: ein Video, das die Sandbox-Adressen und die Events zeigt, die jede davon erzeugt