Envio em lote
POST /v1/email/batches aceita até 100 payloads de envio completos em uma única solicitação. Cada item é uma mensagem independente com seu próprio remetente, destinatários e conteúdo. Use um lote para enviar recibos, alertas ou outras mensagens por destinatário com menos solicitações API. Para uma única mensagem, consulte Envio de e-mail.
Quando usar o quê
- Mensagens independentes que você já tem em mãos. Use um lote e envie todas em uma única solicitação.
- Um fluxo constante de alto volume. Chamar o endpoint de envio individual em um loop é uma arquitetura adequada, e um lote não torna a entrega de cada mensagem mais barata ou mais rápida. O que muda é a vazão, porque as solicitações em lote usam a política de limitação de requisições email_batch em vez da política email_send, e cada uma aceita até 100 mensagens.
- Um e-mail para uma audiência armazenada. Isso é um broadcast, que resolve a audiência em destinatários e personaliza por contato.
Envios em lote
O corpo da solicitação é um objeto JSON cujo array messages contém de 1 a 100 objetos de mensagem. Cada item é uma solicitação de envio completa e independente com seus próprios from, to, subject, conteúdo e, opcionalmente, seus próprios category, ip_pool_id, tags e metadata. O schema do item é exatamente o payload de envio único, então tudo em envio de e-mail se aplica por item, incluindo o padrão category de marketing e o envio por template.
Isso inclui scheduled_at, então um lote pode misturar mensagens enviadas agora com mensagens enviadas depois, cada uma no seu próprio horário. As regras e a margem em envio agendado se aplicam por item, e um item agendado é cancelado pelo seu próprio ID como qualquer outra mensagem agendada.
const batch = await bird.email.sendBatch({
messages: [
{
from: { email: "onboarding@messagebird.dev", name: "Bird" },
to: ["alice@example.com"],
subject: "Your receipt",
html: "<p>Thanks, Alice.</p>",
},
{
from: { email: "onboarding@messagebird.dev", name: "Bird" },
to: ["bob@example.com"],
subject: "Your receipt",
html: "<p>Thanks, Bob.</p>",
},
],
});
for (const item of batch.data) console.log(item.id, item.status);batch = client.email.send_batch(
messages=[
{
"from_": {"email": "onboarding@messagebird.dev", "name": "Bird"},
"to": ["delivered@messagebird.dev"],
"subject": "Hello from Bird",
"html": "<p>My first Bird email.</p>",
},
{
"from_": {"email": "onboarding@messagebird.dev", "name": "Bird"},
"to": ["someone-else@messagebird.dev"],
"subject": "Hello again from Bird",
"text": "My second Bird email.",
},
],
)
for item in batch.data:
print(item.id, item.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)
}
batch, err := client.Email.SendBatch(context.Background(), bird.EmailSendBatchParams{
Messages: []bird.EmailSendParams{
{
From: "onboarding@messagebird.dev",
To: []string{"alice@example.com"},
Subject: "Hello, Alice",
HTML: "<p>Welcome!</p>",
},
{
From: "onboarding@messagebird.dev",
To: []string{"bob@example.com"},
Subject: "Hello, Bob",
HTML: "<p>Welcome!</p>",
},
},
})
if err != nil {
log.Fatal(err)
}
for _, item := range batch.Data {
fmt.Println(item.Id)
}
}$batch = $bird->email->sendBatch(messages: [
(new EmailMessageSendRequest())
->setFrom((new EmailAddress())->setEmail('onboarding@messagebird.dev')->setName('Bird'))
->setTo([(new EmailAddress())->setEmail('delivered@messagebird.dev')])
->setSubject('Hello from Bird')
->setHtml('<p>My first Bird email.</p>'),
(new EmailMessageSendRequest())
->setFrom((new EmailAddress())->setEmail('onboarding@messagebird.dev')->setName('Bird'))
->setTo([(new EmailAddress())->setEmail('someone-else@messagebird.dev')])
->setSubject('Hello again from Bird')
->setText('My second Bird email.'),
]);
foreach ($batch->getData() ?? [] as $item) {
echo $item->getId(), ' ', $item->getStatus(), "\n";
}bird email send-batch --body-file - <<'JSON'
{
"messages": [
{
"from": {
"email": "noreply@acme.com",
"name": "Acme Support"
},
"to": [
{
"email": "delivered@messagebird.dev",
"name": "Jane Doe"
}
],
"subject": "Your receipt for order #1234",
"text": "Thanks for your purchase! Your receipt is attached."
},
{
"from": {
"email": "noreply@acme.com",
"name": "Acme Support"
},
"to": [
{
"email": "delivered@messagebird.dev",
"name": "John Roe"
}
],
"subject": "Your receipt for order #1235",
"text": "Thanks for your purchase! Your receipt is attached."
}
]
}
JSONcurl -X POST https://us1.platform.bird.com/v1/email/batches \
-H "Authorization: Bearer bk_us1_..." \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"from": "hello@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"subject": "Your receipt",
"html": "<p>Thanks for your order.</p>",
"category": "transactional"
},
{
"from": "newsletter@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"subject": "June product news",
"html": "<p>What shipped this month.</p>",
"category": "marketing"
},
{
"from": "alerts@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"subject": "Usage threshold reached",
"text": "You have used 80% of your quota.",
"category": "transactional"
}
]
}'Validação tudo-ou-nada
Todos os itens são validados antes de qualquer item ser enfileirado. Se uma mensagem falhar, seja um erro de validação no nível do campo ou um domínio de remetente não verificado, o lote inteiro é rejeitado com um 422 e nada é enviado: corrija o item e reenvie o lote.
A supressão não faz parte dessa verificação. Um item cujos destinatários são todos suprimidos ainda é aceito e recebe seu próprio ID em_, e esses destinatários retornam como status: rejected depois que a mensagem é processada (consulte supressões).
Processar a resposta 202
Um lote bem-sucedido retorna 202 Accepted com uma entrada por mensagem, na ordem de envio:
Exemplo de código
{
"data": [
{ "id": "em_01ky7q1vmkerwa7fxyycfe5ks1", "status": "accepted", "category": "transactional" },
{ "id": "em_01ky7q1vmkesr9h1y52tkqng9f", "status": "accepted", "category": "marketing" },
{ "id": "em_01ky7q1vmkesyr1z1h4s48jjxm", "status": "accepted", "category": "transactional" }
]
}Cada filho é uma mensagem comum: rastreie-o pelo ID em_ via GET /v1/email/messages/{message_id}, seus endpoints de destinatário e evento, e webhooks, exatamente como se você o tivesse enviado individualmente. O mesmo modelo assíncrono se aplica, então 202 significa aceito de forma durável e os resultados por destinatário chegam depois.
Retentativas idempotentes
A idempotência é opcional. Os SDKs geram uma chave para novas tentativas automáticas. Para novas tentativas entre chamadas separadas ou ao usar HTTP diretamente, consulte o guia de idempotência para saber como reutilizar chaves e quais são os limites de reprodução.
Anexos e o limite do corpo
Cada item do lote pode ter seus próprios attachments, com o mesmo contrato de campo e orçamento de tamanho por mensagem de um envio único (consulte anexos). Mais um limite se aplica ao lote como um todo: o corpo serializado da solicitação JSON é limitado a 20 MB, e um corpo maior é rejeitado com um 413. Anexos codificados em Base64 contam nesse limite, então lotes com muitos anexos atingem o teto rapidamente. Divida-os em vários lotes, ou envie-os um de cada vez.
Broadcasts
Um broadcast envia um e-mail para uma audiência armazenada. Resolvemos os membros atuais da audiência, menos as supressões, na lista de destinatários quando o envio começa, e as propriedades de contato de cada destinatário preenchem as variáveis do template. Dispare um pelo dashboard, pelo /v1/email/broadcasts, ou com os comandos bird email broadcasts. Broadcasts tem o passo a passo.
Próximos passos
- Envio de e-mail: o payload por item completo, incluindo campos, limites, e tags vs metadata
- Broadcasts: um e-mail para uma audiência armazenada, personalizado por contato
- Categorias: marketing e transactional, e o que cada uma faz na política de supressão
- Idempotência: formato da chave, retenção e semântica de replay
- Referência do API: os schemas completos de solicitação e resposta do lote
- Enviar 100 emails numa única chamada API: um vídeo que mostra um lote sendo enviado e como cada mensagem reporta de volta
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Explore a funcionalidadeEmail batch sendingSiga o percurso de aprendizagemBuild your first integration
Obtenha um resumo de implementação