Testare la consegna email (mail sandbox)

Indirizzi magici

Regole di indirizzamento

• Il rilevamento si basa solo sulla local part e solo sul dominio messagebird.dev. bounce@yourdomain.com è un indirizzo normale.
• Solo le local part nella tabella degli indirizzi magici sono magiche. Qualsiasi altro indirizzo su messagebird.dev è un destinatario normale. Quando invii dal dominio di onboarding condiviso, quell'indirizzo deve appartenere a un membro verificato dello spazio di lavoro.
• Il matching è case-insensitive: Bounce@messagebird.dev e bounce@messagebird.dev si comportano in modo identico.
• Il subaddressing +label viene rimosso prima del matching: bounce+signup-flow@messagebird.dev genera comunque un bounce. Usa le label per correlare i casi di test; l'indirizzo completo, label inclusa, compare nei tuoi eventi e webhook, così ogni esecuzione di test può etichettare i propri destinatari.

Procedura guidata: simulare un bounce, dall'inizio alla fine

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

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

Cosa fa e cosa non fa il sandbox

• Nessuna scrittura nella lista di soppressione. I hard bounce e le segnalazioni spam simulati non aggiungono il destinatario alla tua lista di soppressione; è questo che mantiene gli indirizzi riutilizzabili. Il tuo webhook viene comunque attivato (email.bounced, email.complained), quindi la tua logica di soppressione è pienamente esercitata. Per testare il percorso di rifiuto per 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, nessuna casella di posta è coinvolta e la tua reputazione di invio resta intatta.
• La validazione della richiesta si applica comunque. Un invio sandbox utilizza gli endpoint normali, quindi i controlli di schema, i limiti di dimensione e le regole sugli header rifiutano una richiesta non valida come di consueto. Ciò che il sandbox salta è tutto ciò che segue il handoff: il rendering e il comportamento di consegna oltre quel punto non vengono esercitati.
• Aperture e clic non sono 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 sandbox. Gli invii sandbox contano ai fini delle statistiche aggregate del tuo spazio di lavoro e dei tassi di bounce e segnalazioni spam. Un uso intenso di bounce sandbox altera le tue dashboard lasciando inalterata la tua reputazione.

Prossimi passi

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