Testowanie dostarczania e-maili (piaskownica poczty)

Piaskownica poczty pozwala testować obsługę webhooków, logikę suppresji i wyniki dostarczenia bez wysyłania do prawdziwej skrzynki odbiorczej. Wyślij wiadomość przez standardowe API na adres w domenie messagebird.dev. Wynik zależy od części lokalnej adresu: bounce@messagebird.dev zostaje odbity, a delivered@messagebird.dev zostaje dostarczony.

Wysyłka w piaskownicy przechodzi przez standardowe ścieżki akceptacji, zdarzeń i webhooków. Zwraca tę samą odpowiedź 202 i generuje ładunki zdarzeń dla każdego odbiorcy o tym samym kształcie co wysyłka produkcyjna. Ładunek nie zawiera flagi testowej. Wiadomość nie trafia do zewnętrznej infrastruktury dostarczania ani do prawdziwej skrzynki. Symulowane odbicia i skargi nie wpływają na reputację nadawcy i nie są zapisywane na liście suppresji, więc możesz używać tych adresów wielokrotnie.

Piaskownica nie wymaga konfiguracji: nie ma przełącznika, trybu testowego ani specjalnego klucza API. Uruchamia ją wyłącznie adres odbiorcy w standardowych punktach końcowych wysyłki (POST /v1/email/messages i POST /v1/email/batches) oraz w wysyłce masowej. Kontakt z grupy odbiorców, którego adres należy do piaskownicy, jest symulowany zamiast otrzymać wiadomość. W ten sposób przećwiczysz kampanię bez wysyłania poczty do kogokolwiek. Symulowany odbiorca nadal wlicza się do limitu wysyłek, więc próba obciąża ten sam limit co rzeczywista wysyłka.

Magiczne adresy

Wszystkie adresy znajdują się w domenie @messagebird.dev. Wynik zależy od części lokalnej:

Powyższe sekwencje to webhooki generowane przez pojedynczą wysyłkę. W przypadku broadcastu pomiń początkowe email.accepted: odbiorca broadcastu jest akceptowany samodzielnie, ale rejestrujemy to zdarzenie bez wysyłania dla niego webhooka, więc każda sekwencja zaczyna się od kolejnego zdarzenia, czyli email.processed na ścieżkach doręczenia i email.rejected dla suppressed@ i reject@. Wszystko dalej jest identyczne, a pełną regułę opisuje dokumentacja zdarzeń.

Jedna wysyłka może łączyć odbiorców sandboxowych i rzeczywistych. Każdy odbiorca ma własny cykl życia: rzeczywiści odbiorcy otrzymują wiadomość normalnie, a odbiorcy sandboxowi są symulowani.

Te same zdarzenia trafiają też na oś czasu wiadomości w logu e-maili i do zdarzeń API, więc możesz korzystać z sandboxa bez endpointu webhooka i odczytywać wyniki później.

Zasady adresowania

• Wykrywanie odbywa się wyłącznie na podstawie części lokalnej i tylko w domenie messagebird.dev. bounce@yourdomain.com to zwykły adres.
• Magiczne są tylko części lokalne wymienione w tabeli magicznych adresów. Każdy inny adres w messagebird.dev to zwykły odbiorca. Gdy wysyłasz ze współdzielonej domeny onboardingowej, ten adres musi należeć do zweryfikowanego członka obszaru roboczego.
• Dopasowanie nie rozróżnia wielkości liter: Bounce@messagebird.dev i bounce@messagebird.dev działają identycznie.
• Subadresowanie +label jest usuwane przed dopasowaniem: bounce+signup-flow@messagebird.dev nadal generuje odbicie. Używaj etykiet do powiązania przypadków testowych; pełny adres wraz z etykietą pojawia się w zdarzeniach i webhookach, więc każde uruchomienie testu może oznaczać własnych odbiorców.

Przykład: symulacja odbicia od początku do końca

Nie potrzebujesz zweryfikowanej domeny nadawczej. Wysyłaj z onboarding@messagebird.dev, jak opisano w Wyślij swój pierwszy e-mail. Rozpoznane adresy sandboksa są zwolnione z ograniczenia domeny onboardingowej do zweryfikowanych członków, ale nadal wliczają się do jej dziennego limitu.

Upewnij się, że masz endpoint webhooka subskrybujący zdarzenia e-mail (zobacz Webhooki), a następnie wyślij:

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

Jeśli Twój klucz zaczyna się od bk_eu1_, wywołaj zamiast tego https://eu1.platform.bird.com.

API odpowiada 202 Accepted z identyfikatorem wiadomości em_*, nieodróżnialnym od wysyłki produkcyjnej. Właśnie o to chodzi: testujesz swoją rzeczywistą ścieżkę kodu. Twój endpoint webhooka otrzymuje następnie email.accepted, email.processed i na końcu email.bounced. Każde zdarzenie powtarza tags i metadata wysyłki (null, jeśli wysyłka ich nie miała), a payload email.bounced zawiera pełną klasyfikację odbicia:

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

Znaczenie pól opisuje dokumentacja zdarzeń. W payloadzie nie ma żadnej flagi symulatora: typ i struktura zdarzenia są dokładnie takie, jakie tworzy rzeczywiste twarde odbicie. Symulację identyfikuje tylko sam adres odbiorcy, więc jeśli Twój handler musi osobno obsługiwać ruch testowy, opieraj się na domenie odbiorcy messagebird.dev.

Aby sprawdzić, że do odbiorcy już objętego suppresją nic nie zostaje wysłane, powtórz wysyłkę z suppressed@messagebird.dev. Sprawdź, że otrzymujesz email.accepted, a następnie email.rejected z rejection_reason: "recipient_suppressed". Nie powinieneś otrzymać email.processed ani zdarzeń dostarczenia. Odpowiada to dokładnie rzeczywistemu odbiorcy objętemu suppresją: wiadomość zostaje przyjęta, a potem przerwana podczas przetwarzania, zanim cokolwiek zostanie wysłane.

Co sandbox robi, a czego nie

• Brak zapisów na listę suppresji. Symulowane twarde odbicia i skargi nie dodają odbiorcy do Twojej listy suppresji; dzięki temu adresy można używać ponownie. Twój webhook nadal się uruchamia (email.bounced, email.complained), więc Twoja własna logika suppresji zostaje w pełni sprawdzona. Aby przetestować ścieżkę odrzucenia odbiorcy już objętego suppresją, użyj dedykowanego adresu suppressed@.
• Nigdy nie ma rzeczywistego dostarczenia. Odbiorcy sandboksa są przechwytywani, zanim wiadomość dotrze do infrastruktury dostarczania. Nic nie jest przesyłane, żadna skrzynka nie bierze udziału, a Twoja reputacja nadawcy pozostaje nienaruszona.
• Walidacja żądań nadal obowiązuje. Wysyłka w sandboksie korzysta ze zwykłych endpointów, więc kontrole schematu, limity rozmiaru i reguły nagłówków odrzucają nieprawidłowe żądanie jak zwykle. Sandbox pomija wszystko po przekazaniu wiadomości: renderowanie i dostarczanie poza tym punktem nie są sprawdzane.
• Otwarcia i kliknięcia nie są symulowane. Magiczny adres symuluje wynik transmisji i nikt nie otwiera wiadomości, więc email.opened i email.clicked pochodzą wyłącznie z rzeczywistej poczty.
• Statystyki obejmują ruch z piaskownicy. Wysyłki do piaskownicy wliczają się do zbiorczych statystyk obszaru roboczego oraz do wskaźników odbić i skarg. Duża liczba odbić w piaskownicy zniekształca dane na pulpitach, ale nie wpływa na Twoją reputację.

Kolejne kroki

• Zdarzenia: pełny słownik zdarzeń i cykl życia każdego odbiorcy
• Webhooki: subskrypcja, weryfikacja podpisu i ponowne próby
• Wyślij pierwszy e-mail: szybki start z domeną onboardingową, na którym opiera się ten przewodnik
• Suppresje: jak działa prawdziwa lista suppresji
• Testowanie e-maili bez spamowania kogokolwiek: film omawiający adresy piaskownicy i zdarzenia generowane przez każdy z nich