Enviando e-mail
POST /v1/email/messages envia um e-mail. Forneça um remetente, destinatários e conteúdo em um payload JSON. A API retorna 202 Accepted com um ID de mensagem e então entrega o e-mail de forma assíncrona. Consulte a referência da API para os schemas completos.
Um envio mínimo
O menor payload válido é um from, pelo menos um destinatário to, um subject e um corpo (html, text, ou ambos). O endereço from precisa estar em um domínio que você verificou neste espaço de trabalho, ou no domínio de onboarding.
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.devcurl -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>"
}'Use o host regional (https://us1.platform.bird.com ou https://eu1.platform.bird.com) com uma chave bk_{region}_... correspondente.
O exemplo de envio usa delivered@messagebird.dev, um endereço sandbox que sempre aceita e-mails. A API rejeita domínios de placeholder com um 422: example.com, example.net, example.org, example.edu, test.com, e qualquer coisa sob os TLDs reservados .test, .example, .invalid ou .localhost. Um envio para esses domínios só pode resultar em bounce, o que prejudica sua reputação de remetente.
Enviando antes de verificar um domínio
Durante o onboarding, você pode enviar a partir do nosso domínio compartilhado de onboarding, onboarding@messagebird.dev. Esses envios ignoram a verificação de domínio, mas alcançam apenas membros verificados do seu próprio espaço de trabalho e endereços sandbox, com um limite diário de destinatários. O quickstart contém as regras e os limites exatos.
Montando o payload
Destinatários
to, cc e bcc aceitam até 50 endereços cada, e to exige pelo menos um. Cada entrada é uma string de e-mail simples, uma string de mailbox RFC 5322 (Jane <jane@acme.com>) ou um objeto com um nome de exibição opcional.
Destinatários na lista de supressão do espaço de trabalho não causam falha na solicitação. Ela ainda retorna um 202, e cada destinatário suprimido aparece nos endpoints de leitura como status: rejected com o motivo recipient_suppressed, inclusive quando isso se aplica a todos os destinatários do envio.
Conteúdo
subject é obrigatório para envios inline, com até 998 caracteres. Forneça html, text ou ambos, cada um com até 524.288 caracteres. Envie ambos sempre que possível: um cliente que não consegue renderizar HTML recorre à parte de texto.
Para personalizar conteúdo inline, coloque tokens {{ variable }} no assunto ou no corpo e passe os valores deles em parameters, com até 16 KB serializados. Um único conjunto de valores se aplica a todos os destinatários do envio, e um token sem chave correspondente é renderizado vazio. Para conteúdo que você reutiliza, envie um template.
Inclua parameters, mesmo como um objeto vazio ({}), para processar o assunto e o corpo como Liquid. Omita-o para enviar tokens como {{ animal }} exatamente como escritos. Cada nome de parâmetro é uma palavra única, como first_name; nomes com pontos e o nome reservado bird são rejeitados. Sintaxe Liquid inválida e tags ou filtros não suportados retornam 422.
Valores inseridos em HTML são escapados para que não alterem a marcação ao redor. Para um link ou URL de imagem completo, use {{ link }} sem url_encode. Para um valor dentro da query de uma URL, codifique esse valor explicitamente, por exemplo https://example.com/search?q={{ query | url_encode }}.
Reply-to e headers personalizados
reply_to aceita de 1 a 25 endereços, nos mesmos formatos que os destinatários. Toda resposta de destinatário vai para todos eles, então o comum é usar um ou dois.
headers é um objeto string-para-string para seus próprios headers, por exemplo {"X-Campaign": "spring-2026"}, limitado a 25 headers com valores de até 998 caracteres. Dois tipos de header retornam um 422:
- 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. - Qualquer valor com retorno de carro ou quebra de linha.
Envios transacionais aceitam List-Unsubscribe e List-Unsubscribe-Post. Envios de marketing usam por padrão o cancelamento de inscrição gerenciado pela Bird.
Rastreamento
track_opens e track_clicks têm como padrão true. Defina qualquer um como false para pular a injeção de pixel de abertura ou a reescrita de links neste envio. Essas flags mantêm intactos os pixels de rastreamento e os links que já estão no conteúdo que você envia. Rastreamento e métricas explica o que cada uma altera na mensagem.
Categoria e pool de IPs
category classifica o conteúdo e define a política de supressão: marketing bloqueia a entrega em qualquer motivo de supressão e em qualquer opt-out, e transactional entrega mesmo com uma supressão por reclamação ou um opt-out apenas de marketing (um opt-out registrado para todas as mensagens também bloqueia a entrega). O padrão é a categoria do template em um envio com template e marketing nos demais casos, então defina transactional explicitamente para recibos, redefinições de senha e outros e-mails operacionais. Categorias explica a escolha. E-mails enviados via SMTP usam a categoria da configuração SMTP da chave.
ip_pool_id seleciona o pool de envio: um ID de pool (ipp_...), ou ipp_shared para rotear explicitamente pelo pool compartilhado. Omita-o para usar o pool padrão da sua organização. Um pool desconhecido, ou sem IPs dedicados disponíveis para envio, é rejeitado com um 422.
Referência de campos
| Campo | Tipo | Obrigatório | Limites e observações |
|---|---|---|---|
from | address | sim | Deve estar em um domínio verificado, ou no domínio de onboarding |
to | address[] | sim | 1 a 50 |
cc, bcc | address[] | não | Até 50 cada |
subject | string | envios inline | Até 998 caracteres; omita em envios com template |
html, text | string | pelo menos um | Até 524.288 caracteres cada; omita em envios com template |
reply_to | address[] | não | 1 a 25; respostas vão para todos os endereços listados |
headers | object (string → string) | não | Até 25; nomes reservados são rejeitados (veja headers personalizados) |
parameters | object | não | Valores para {{ tokens }} em conteúdo inline; até 16 KB serializados; compartilhados entre destinatários |
tags | {name, value}[] | não | Até 20; nome ≤ 32 chars, valor ≤ 64 chars; apenas [A-Za-z0-9_-]; nomes únicos por envio |
metadata | object | não | JSON arbitrário, até 2 KB serializado |
reference | string | não | 1 a 255 caracteres; correspondência exata para ?reference= na lista de mensagens |
track_opens | boolean | não | Padrão true |
track_clicks | boolean | não | Padrão true |
category | string | não | marketing ou transactional; padrão é o do template em envio com template, caso contrário marketing |
ip_pool_id | string | não | ipp_... ou ipp_shared; omita para usar o pool padrão da sua organização |
template | object | não | Envia um template publicado por id ou slug, com parameters para suas variáveis e um language opcional |
attachments | object[] | não | Até 20; veja anexos |
scheduled_at | timestamp RFC 3339 | não | Agende conteúdo inline ou um template; veja envio agendado |
Enviando com um template
Templates podem usar valores bird.contact.* do contato correspondente a cada endereço To. Os destinatários Cc e Bcc recebem uma cópia do e-mail personalizado de cada destinatário To. Isso também funciona no API em lote e em envios agendados; veja personalizando com variáveis para um exemplo com vários destinatários.
Em vez de conteúdo inline, envie um template publicado: defina template como um objeto nomeando-o por id (emt_...) ou por slug, exatamente um dos dois, com os valores das variáveis em template.parameters. Omita subject, html e text, porque o template já os contém.
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.devcurl -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" }
}
}'O conteúdo de um template é Liquid, então além da substituição simples de {{ variable }} ele pode usar filtros, condicionais {% if %} e loops {% for %}. Personalizando com variáveis lista os poucos construtos que uma publicação rejeita. template.parameters é onde você coloca os valores para os parâmetros do próprio template, indexados por nome. Se você omitir um deles, o envio é rejeitado com um 422 que o identifica. O envio aceita os mesmos tags, metadata, rastreamento e anexos que o e-mail inline. O que é específico de um envio com template:
- Inline ou com template, nunca ambos. Enviar
templatejunto comsubject,htmloutexté rejeitado com um422. A API também rejeita valores de variáveis no campo de nível superiorparameters; em um envio com template eles pertencem atemplate.parameters. birdé o único nome reservado. Um caminho de placeholder que começa combird.nomeia dados nossos, como o link de cancelamento de inscrição ou o registro de contato do destinatário, então uma chavetemplate.parametersnão pode se chamarbird. 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_atpara agendar o envio. Salvamos a versão publicada, o idioma selecionado, os parâmetros do chamador e os valores dos contatos no momento da aceitação, para que edições posteriores de contatos ou de valores de fallback não alterem mensagens já aceitas. Se você excluir o template antes do horário de envio, a mensagem é rejeitada comgeneration_failure. - Personalize com atributos de contato. Consulte requisitos de contato e saudações padrão.
- A correspondência de contatos ignora nomes de exibição. Os endereços de e-mail são convertidos para minúsculas, preservando pontos e tags com sinal de mais. Se vários contatos compartilharem esse endereço, o envio retorna
EmailTemplateContactAmbiguous; atualize os registros duplicados antes de tentar novamente. - O envio usa permissões de e-mail. Uma chave com
emails:writepode enviar um template publicado sem permissão de descoberta de contatos.emails:readconcede acesso ao conteúdo não sensível da mensagem resultante. A descoberta de contatos e de propriedades mantém as permissões existentes. - 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 um422. languageescolhe 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çãoon_missing_languagedele decide se a correspondência mais próxima é enviada ou se o envio é rejeitado. Um template que definelanguage_source_requiredrejeita um envio que não especifica nenhum idioma.- A categoria do template é um padrão, e a sua a substitui. Omita
categorye o envio herda a do template, então um template transacional não precisa repeti-la em cada chamada.
Templates de e-mail cobre criação, publicação e os construtos que um template pode conter.
Ler o conteúdo de um destinatário
O histórico de mensagens com template usa os valores de contato salvos quando o envio foi aceito, mesmo que você edite ou exclua o contato depois. Cada entrega copiada tem seu próprio ID de destinatário.
Liste os destinatários da mensagem para obter os IDs deles e, em seguida, passe recipient_id para Get stored message content. Uma nova mensagem com template que tem snapshots de vários destinatários retorna 422 sem esse seletor. Um destinatário único é selecionado automaticamente; um destinatário que pertence a outra mensagem retorna 404.
As respostas de GET e de listagem de mensagens usam o assunto aceito do primeiro destinatário To, identificado por subject_recipient_id. A listagem de destinatários fornece o assunto de cada destinatário. Esses assuntos continuam disponíveis quando o armazenamento do corpo está desativado. As leituras de conteúdo ainda seguem as configurações de armazenamento e retenção da mensagem, incluindo 404 quando o conteúdo não é armazenado, 425 enquanto está pendente e 410 após a expiração.
Se um snapshot de destinatário retido ficar indisponível, o status da mensagem e o assunto representativo continuam legíveis, mas os assuntos por destinatário são omitidos e o conteúdo fica indisponível. As leituras não consultam os valores atuais dos contatos para reconstruir um envio anterior.
Tags vs metadata
Esses campos associam seus próprios dados a um envio e diferem na forma como você os consulta depois:
tagssã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 comocampaign,experiment_variantousource.metadataé um objeto JSON arbitrário, com até 2 KB serializado. Nós o armazenamos, o retornamos em leituras API e o incluímos nos eventos de webhook quando disponível, então ele é ideal para contexto que você quer receber de volta: IDs internos, chaves estrangeiras, payloads estruturados.referenceé uma string de 1 a 255 caracteres pela qual você quer encontrar a mensagem, como um número de pedido ou de ticket.GET /v1/email/messages?reference=faz a correspondência exata, diferenciando maiúsculas de minúsculas, e várias mensagens podem compartilhar o mesmo valor. Ele é retornado nas leituras e incluído nos eventos de webhook da mensagem. Defina-o apenas quando precisar pesquisar por ele e coloque qualquer outro dado emmetadata.
Armazene o ID da mensagem junto com o seu próprio registro de cliente para correlacionar os webhooks. Tags e metadata podem vir nulos em eventos de cancelamento de inscrição mesmo quando você os forneceu: links de cancelamento de inscrição Bird retornam nulo para envios individuais, e opt-outs de broadcast podem retornar nulo quando esse contexto não está disponível. Consulte o envelope do evento para mais detalhes. Nomes de tag e chaves de metadata de nível superior que começam com __bird são rejeitados. Você não precisa codificar dispositivo, geografia, provedor de caixa de correio, tipo de bounce ou domínio do destinatário em nenhum dos campos, porque já capturamos cada um desses como uma dimensão de analytics.
{
"tags": [{ "name": "campaign", "value": "onboarding" }],
"metadata": { "user_id": "usr_12345", "order_id": "ord_98765" },
"reference": "ord_98765"
}Anexos
attachments aceita até 20 arquivos por mensagem, como bytes codificados em base64 inline. Rejeitamos um envio cujo tamanho estimado da mensagem gerada exceda 20 MB, medido após a codificação base64, então mantenha o conteúdo bruto dos anexos em até 15 MB para margem. Anexos contém o contrato de campos, imagens inline, os tipos de arquivo bloqueados e como baixar um anexo de volta.
O que um 202 significa
Um envio bem-sucedido retorna 202 Accepted com um ID de mensagem prefixado por em_ e status: accepted:
{
"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"
}O 202 significa que aceitamos o envio de forma durável. Falhas que você pode corrigir voltam na própria requisição como 422: um domínio de remetente não verificado ou um campo que não passa na validação. Os resultados por destinatário (entregue, devolvido, adiado, reclamado) chegam depois por meio de webhooks e dos endpoints de leitura de mensagens.
Duas coisas decorrem disso:
- Leituras retornam o estado sem o corpo.
GET /v1/email/messages/{message_id}retorna o estado da mensagem e do destinatário, nunca o corpohtmloutext. 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 deGET /v1/email/messages/{message_id}/content. - Uma leitura pode demorar um instante após o envio. Um
404nos endpoints de leitura logo após um202significa que a mensagem ainda não está visível; tente novamente em um momento.
Tentando novamente com segurança
Envie um header Idempotency-Key com um valor único por envio lógico. Se uma requisição foi bem-sucedida mas você não viu a resposta, reenvie-a com a mesma chave. A API retorna o resultado original em vez de enviar um segundo e-mail e inclui um header Idempotency-Replay. Idempotência contém o formato da chave e a retenção.
Envio em lote
Para reduzir requisições API, POST /v1/email/batches aceita até 100 mensagens independentes e as valida como uma unidade. Chamar o endpoint de envio individual em um loop também é suportado. Um item de lote usa o payload desta página, incluindo scheduled_at, então um lote pode misturar mensagens imediatas e agendadas.
Custo e faturamento
Os envios de e-mail são medidos por destinatário, então uma mensagem para três destinatários conta como três envios. No plano Email Free, os envios são descontados da cota mensal e diária do plano. Em um plano Email pago, cada envio é cobrado da sua carteira pela tarifa do plano a cada 1.000 e-mails. Faturamento e uso cobre o modelo de medição e a leitura de uso em tempo real, e a página de preços de e-mail lista a tarifa de cada plano.
Próximos passos
- Templates de e-mail: crie e publique os templates que você envia por aqui
- Categorias: como
marketingetransactionalalteram 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
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.