Testar entrega de e-mail (sandbox de e-mail)

Endereços mágicos

Regras de endereçamento

• A detecção é apenas pela parte local, e somente no domínio messagebird.dev. bounce@yourdomain.com é um endereço normal.
• Apenas as partes locais na tabela de endereços mágicos são mágicas. Qualquer outro endereço em messagebird.dev é um destinatário normal. Quando você envia pelo domínio compartilhado de onboarding, esse endereço precisa pertencer a um membro verificado do espaço de trabalho.
• A correspondência não diferencia maiúsculas de minúsculas: Bounce@messagebird.dev e bounce@messagebird.dev se comportam de forma idêntica.
• O subendereçamento +label é removido antes da correspondência: bounce+signup-flow@messagebird.dev ainda causa bounce. Use labels para correlacionar casos de teste; o endereço completo, incluindo o label, aparece nos seus eventos e webhooks, então cada execução de teste pode marcar seus próprios destinatários.

Passo a passo: simular um bounce, de ponta a ponta

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

O que o sandbox faz e não faz

• Sem gravação na lista de supressão. Hard bounces e reclamações simulados não adicionam o destinatário à sua lista de supressão; é isso que mantém os endereços reutilizáveis. Seu webhook ainda dispara (email.bounced, email.complained), então a sua própria lógica de supressão é totalmente exercitada. Para testar o caminho de rejeição de já suprimido, use o endereço dedicado suppressed@.
• Sem entrega real, nunca. Destinatários de sandbox são interceptados antes de a mensagem alcançar a infraestrutura de entrega. Nada é transmitido, nenhuma caixa de entrada é envolvida, e sua reputação de envio permanece intacta.
• A validação da solicitação ainda se aplica. Um envio pelo sandbox usa os endpoints normais, então verificações de schema, limites de tamanho e regras de cabeçalho rejeitam uma solicitação inválida normalmente. O que o sandbox pula é tudo após a transferência: renderização e comportamento de entrega além desse ponto não são exercitados.
• Aberturas e cliques não são simulados. Um endereço mágico simula o resultado da transmissão, e ninguém abre a mensagem, então email.opened e email.clicked vêm apenas de e-mails reais.
• As estatísticas incluem tráfego de sandbox. Envios pelo sandbox contam nas estatísticas agregadas do seu espaço de trabalho e nas taxas de bounce e reclamação. Bounces intensos pelo sandbox distorcem seus dashboards, mas deixam sua reputação inalterada.

Próximos passos

• Eventos: o vocabulário completo de eventos e o ciclo de vida por destinatário
• Webhooks: inscrição, verificação de assinatura e novas tentativas
• Envie seu primeiro e-mail: o quickstart do domínio de onboarding em que este passo a passo se baseia
• Supressões: como a lista de supressão real funciona
• Testar emails sem incomodar ninguém: um vídeo que percorre os endereços de sandbox e os eventos que cada um produz