Enviando e-mail

Um envio mínimo

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});
console.log(msg.id, msg.status); // "em_…", "accepted"

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["delivered@messagebird.dev"],
    subject="Hello from Bird",
    html="<p>My first Bird email.</p>",
)
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{"delivered@messagebird.dev"},
		Subject: "Hello from Bird",
		HTML:    "<p>My first Bird email.</p>",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    subject: 'Hello from Bird',
    html: '<p>My first Bird email.</p>',
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --from hello@yourdomain.com \
  --html '<p>It works.</p>' \
  --subject 'Hello from Bird' \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Hello from Bird",
    "html": "<p>It works.</p>"
  }'

Enviando antes de verificar um domínio

Montando o payload

Destinatários

Conteúdo

Reply-to e headers personalizados

• Headers de endereçamento e plataforma. Defina o endereçamento da mensagem pelos campos dedicados (from, to, cc, bcc, reply_to, subject). Esses nomes, e os headers que geramos para você (Content-Type, Content-Transfer-Encoding, DKIM-Signature, Received, Return-Path), não podem ser definidos aqui.
• List-Unsubscribe e List-Unsubscribe-Post em um envio marketing. Nós definimos um header de cancelamento de inscrição com um clique em conformidade nesses casos. Em um envio transactional, mantemos os seus exatamente como você definiu.
• Qualquer valor com retorno de carro ou quebra de linha.

Rastreamento

Categoria e pool de IPs

Referência de campos

Enviando com um template

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  category: "transactional",
  template: {
    slug: "welcome-email",
    parameters: { first_name: "Jane" },
  },
});
console.log(msg.id, msg.status);

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["delivered@messagebird.dev"],
    category="transactional",
    template="welcome-email",
    parameters={"first_name": "Jane"},
)
print(msg.id, msg.status)

msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:       "onboarding@messagebird.dev",
	To:         []string{"delivered@messagebird.dev"},
	Category:   "transactional",
	Template:   "welcome-email",
	Parameters: map[string]any{"first_name": "Jane"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    category: 'transactional',
    template: (new EmailMessageSendRequestTemplate())
        ->setSlug('welcome-email')
        ->setParameters(['first_name' => 'Jane']),
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --category transactional \
  --from hello@yourdomain.com \
  --parameters '{"first_name":"Jane"}' \
  --template welcome-email \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "category": "transactional",
    "template": {
      "slug": "welcome-email",
      "parameters": { "first_name": "Jane" }
    }
  }'

• Inline ou com template, nunca ambos. Enviar template junto com subject, html ou text é rejeitado com um 422. A API também rejeita valores de variáveis no campo de nível superior parameters; em um envio com template eles pertencem a template.parameters.
• bird é o único nome reservado. Um caminho de placeholder que começa com bird. nomeia dados nossos, como o link de cancelamento de inscrição ou o registro de contato do destinatário, então uma chave template.parameters não pode se chamar bird. Todas as outras chaves são suas, e cada uma é uma palavra simples: {"order_number": "A-1043"} preenche {{ order_number }}.
• Um template pode ser enviado agora ou depois. Adicione scheduled_at para agendar o envio. Nós fixamos a versão publicada, o idioma selecionado e os valores dos parâmetros no momento da aceitação. Se você excluir o template antes do horário de envio, a mensagem é rejeitada com generation_failure.
• Um envio usa a versão publicada do template. Rascunhos nunca são enviados. Um template desconhecido é rejeitado com um 404, e um template sem versão publicada com um 422.
• language escolhe um dos idiomas do template. Omita-o para enviar o padrão do template. Solicite um que o template não possui, e a configuração on_missing_language dele decide se a correspondência mais próxima é enviada ou se o envio é rejeitado. Um template que define language_source_required rejeita um envio que não especifica nenhum idioma.
• A categoria do template é um padrão, e a sua a substitui. Omita category e o envio herda a do template, então um template transacional não precisa repeti-la em cada chamada.

Tags vs metadata

• tags são pares {name, value} estruturados: até 20 por envio, nome com até 32 caracteres, valor com até 64, apenas letras ASCII, dígitos, underscore e hífen, e nomes únicos dentro do envio. Tags são dimensões de filtro, então você pode filtrar a lista de mensagens por tag e segmentar analytics e resumos do dashboard por tag. Use-as para rótulos de baixa cardinalidade como campaign, experiment_variant ou source.
• metadata é um objeto JSON arbitrário, até 2 KB serializado. Nós o armazenamos, retornamos em leituras API e o incluímos em cada evento de webhook, então ele é ideal para contexto que você quer de volta: IDs internos, chaves estrangeiras, payloads estruturados.

{
  "tags": [{ "name": "campaign", "value": "onboarding" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" }
}

Anexos

O que um 202 significa

{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "hello@yourdomain.com" },
  "to": [{ "email": "delivered@messagebird.dev" }],
  "subject": "Hello from Bird",
  "accepted_count": 1,
  "processed_count": 0,
  "delivered_count": 0,
  "deferred_count": 0,
  "bounced_count": 0,
  "complained_count": 0,
  "rejected_count": 0,
  "open_count": 0,
  "click_count": 0,
  "track_opens": true,
  "track_clicks": true,
  "created_at": "2026-07-23T13:58:20.866Z"
}

• Leituras retornam o estado sem o corpo. GET /v1/email/messages/{message_id} retorna o estado da mensagem e do destinatário, nunca o corpo html ou text. Quando o armazenamento de conteúdo está ativado para o espaço de trabalho, os corpos armazenados ficam disponíveis por até 30 dias a partir de GET /v1/email/messages/{message_id}/content.
• Uma leitura pode demorar um instante após o envio. Um 404 nos endpoints de leitura logo após um 202 significa que a mensagem ainda não está visível; tente novamente em um momento.

Tentando novamente com segurança

Envio em lote

Faturamento

Próximos passos

• Templates de e-mail: crie e publique os templates que você envia por aqui
• Categorias: como marketing e transactional alteram o comportamento de supressão
• Supressões: para quem não entregamos, e por quê
• Envio agendado: entregue em um horário futuro com scheduled_at
• Sandbox de testes: destinatários sandbox e envio antes da verificação
• Referência do API: os schemas completos de requisição e resposta