Testare la consegna delle email (sandbox di posta)

La sandbox di posta consente di testare gli handler dei webhook, la logica di soppressione e gli esiti di consegna senza inviare a una casella di posta reale. Invia tramite il normale API a un indirizzo su messagebird.dev. La parte locale determina l'esito: bounce@messagebird.dev genera un bounce e delivered@messagebird.dev viene consegnato.

Un invio alla sandbox usa i normali percorsi di accettazione, eventi e webhook. Restituisce la stessa risposta 202 e produce, per ogni destinatario, payload di evento con la stessa struttura di un invio in produzione. Il payload non contiene alcun flag di test. Il messaggio non raggiunge l'infrastruttura di consegna esterna né una casella di posta reale. I bounce e le segnalazioni di spam simulati non influiscono sulla reputazione di invio e non scrivono nella lista di soppressione, quindi puoi riutilizzare gli indirizzi.

La sandbox non richiede alcuna configurazione: nessun interruttore, nessuna modalità di test, nessuna chiave API speciale. Si attiva solo in base all'indirizzo del destinatario, sugli endpoint di invio normali (POST /v1/email/messages e POST /v1/email/batches) e su un broadcast. Un contatto del pubblico con un indirizzo della sandbox viene simulato anziché ricevere l'invio: così puoi provare una campagna senza inviare email a nessuno. Un destinatario simulato viene comunque conteggiato nella tua quota di invio, quindi la prova consuma la stessa quota dell'invio reale.

Indirizzi speciali

Tutti gli indirizzi sono su @messagebird.dev. La parte locale seleziona l'esito:

Le sequenze sopra sono i webhook prodotti da un singolo invio. In un broadcast, togli il email.accepted iniziale: un destinatario di un broadcast viene accettato a sé, ma registriamo quell'evento senza inviare un webhook, quindi ogni sequenza inizia dall'evento successivo, email.processed nei percorsi di consegna e email.rejected per suppressed@ e reject@. Tutto il resto è identico, e il riferimento sugli eventi descrive la regola per intero.

Un invio può combinare destinatari sandbox e reali. Ogni destinatario ha il proprio ciclo di vita: i destinatari reali ricevono normalmente, quelli sandbox vengono simulati.

Gli stessi eventi compaiono anche nella cronologia del messaggio nel log delle email e negli eventi API, quindi puoi usare la sandbox anche senza un endpoint webhook e rileggere i risultati.

Regole per gli indirizzi

• Il rilevamento avviene solo in base alla parte locale e solo sul dominio messagebird.dev. bounce@yourdomain.com è un indirizzo normale.
• Sono magiche solo le parti locali presenti nella tabella degli indirizzi magici. Qualsiasi altro indirizzo su messagebird.dev è un destinatario normale. Se invii dal dominio di onboarding condiviso, quell'indirizzo deve appartenere a un membro verificato dello spazio di lavoro.
• La corrispondenza non distingue tra maiuscole e minuscole: Bounce@messagebird.dev e bounce@messagebird.dev si comportano allo stesso modo.
• Il sottoindirizzamento +label viene rimosso prima del confronto: bounce+signup-flow@messagebird.dev genera comunque un bounce. Usa le etichette per correlare i casi di test: l'indirizzo completo, etichetta inclusa, compare nei tuoi eventi e webhook, così ogni esecuzione di test può contrassegnare i propri destinatari.

Procedura completa: simulare un bounce

Non ti serve un dominio di invio verificato. Invia da onboarding@messagebird.dev, come descritto in Invia la tua prima email. Gli indirizzi sandbox riconosciuti sono esenti dalla restrizione del dominio di onboarding sui membri verificati, ma rientrano comunque nella sua quota giornaliera.

Assicurati di avere un endpoint webhook iscritto agli eventi email (vedi Webhook), poi invia:

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

Se la tua chiave inizia con bk_eu1_, chiama invece https://eu1.platform.bird.com.

API risponde 202 Accepted con un ID messaggio em_*, identico a quello di un invio in produzione. Così il percorso di codice che stai testando è quello reale. Il tuo endpoint webhook riceve poi email.accepted, email.processed e infine email.bounced. Ogni evento riporta tags e metadata dell'invio (null se l'invio non li aveva), e il payload email.bounced contiene la classificazione completa del bounce:

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

Il significato dei campi è descritto nel riferimento degli eventi. Il payload non contiene alcun flag di simulazione: il tipo e la struttura dell'evento sono esattamente quelli prodotti da un hard bounce reale. L'unico elemento che lo identifica come simulato è l'indirizzo del destinatario, quindi se il tuo handler deve trattare a parte il traffico di test, basati sul dominio del destinatario messagebird.dev.

Per verificare che a un destinatario già soppresso non venga mai inviato nulla, ripeti l'invio con suppressed@messagebird.dev. Verifica di ricevere email.accepted, poi email.rejected con rejection_reason: "recipient_suppressed". Non devi ricevere email.processed né eventi di consegna. Il comportamento è identico a quello di un destinatario soppresso reale: il messaggio viene accettato, poi interrotto durante l'elaborazione prima di qualsiasi invio.

Cosa fa e cosa non fa la sandbox

• Nessuna scrittura nella lista di soppressione. Gli hard bounce e i reclami simulati non aggiungono il destinatario alla tua lista di soppressione; per questo gli indirizzi restano riutilizzabili. Il tuo webhook viene comunque attivato (email.bounced, email.complained), quindi la tua logica di soppressione viene testata per intero. Per testare il rifiuto di un destinatario già soppresso, usa l'indirizzo dedicato suppressed@.
• Nessuna consegna reale, mai. I destinatari sandbox vengono intercettati prima che il messaggio raggiunga l'infrastruttura di consegna. Non viene trasmesso nulla, non è coinvolta alcuna casella di posta e la tua reputazione di invio resta invariata.
• La validazione della richiesta si applica comunque. Un invio sandbox usa gli endpoint normali, quindi i controlli dello schema, i limiti di dimensione e le regole sugli header rifiutano come di consueto una richiesta non valida. La sandbox salta tutto ciò che avviene dopo il passaggio di consegna: il rendering e il comportamento di consegna oltre quel punto non vengono testati.
• Aperture e clic non vengono simulati. Un indirizzo magico simula il risultato della trasmissione e nessuno apre il messaggio, quindi email.opened e email.clicked provengono solo da email reali.
• Le statistiche includono il traffico della sandbox. Gli invii alla sandbox rientrano nelle statistiche aggregate dello spazio di lavoro e nei tassi di bounce e di reclami. Molti bounce simulati falsano le dashboard, ma lasciano invariata la tua reputazione.

Passaggi successivi

• Eventi: l'elenco completo degli eventi e il ciclo di vita per destinatario
• Webhook: sottoscrizione, verifica della firma e nuovi tentativi
• Invia la tua prima email: la guida rapida sul dominio di onboarding su cui si basa questa procedura
• Soppressioni: come funziona la vera lista di soppressione
• Testare le email senza inviare spam a nessuno: un video che illustra gli indirizzi della sandbox e gli eventi generati da ciascuno