Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Invio batch

POST /v1/email/batches accetta fino a 100 payload di invio completi in una sola richiesta. Ogni elemento è un messaggio indipendente con mittente, destinatari e contenuto propri. Usa un batch per inviare ricevute, notifiche o altri messaggi per destinatario con meno richieste API. Per un singolo messaggio, vedi Invio di email.

Quando usare cosa

  • Messaggi indipendenti già pronti. Usa un batch e consegnali tutti in una sola richiesta.
  • Un flusso costante ad alto volume. Chiamare l'endpoint di invio singolo in un ciclo è un'architettura valida, e un batch non rende nessun singolo messaggio più economico o più veloce da recapitare. Quello che cambia è il throughput, perché le richieste batch attingono al gruppo di limitazione delle richieste email_batch anziché al gruppo email_send, e ciascuna può contenere fino a 100 messaggi.
  • Una sola email a un pubblico salvato. Si tratta di un broadcast, che risolve il pubblico in destinatari e personalizza per contatto.

Invii batch

Il corpo della richiesta è un oggetto JSON il cui array messages contiene da 1 a 100 oggetti messaggio. Ogni elemento è una richiesta di invio completa e indipendente con i propri from, to, subject, contenuto e, facoltativamente, i propri category, ip_pool_id, tag e metadati. Lo schema dell'elemento è esattamente il payload di invio singolo, quindi tutto ciò che è descritto in invio di email si applica per elemento, incluso il valore predefinito category di marketing e l'invio tramite template.
Questo include scheduled_at, quindi un batch può mescolare messaggi da inviare subito con messaggi da inviare più tardi, ognuno al proprio orario. Le regole e i limiti descritti in invio programmato si applicano per elemento, e un elemento programmato viene annullato tramite il proprio ID come qualsiasi altro messaggio programmato.
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);

Validazione tutto-o-niente

Ogni elemento viene validato prima che qualsiasi elemento venga accodato. Se un messaggio fallisce, per un errore di validazione a livello di campo o un dominio mittente non verificato, l'intero batch viene rifiutato con un 422 e nulla viene inviato: correggi quell'elemento e reinvia il batch.
La soppressione non fa parte di quel controllo. Un elemento i cui destinatari sono tutti soppressi viene comunque accettato e riceve il proprio ID em_, e quei destinatari risultano come status: rejected una volta che il messaggio è stato elaborato (vedi soppressioni).

Gestire la risposta 202

Un batch riuscito restituisce 202 Accepted con una voce per messaggio, nell'ordine di invio:
Esempio di codice
{
  "data": [
    { "id": "em_01ky7q1vmkerwa7fxyycfe5ks1", "status": "accepted", "category": "transactional" },
    { "id": "em_01ky7q1vmkesr9h1y52tkqng9f", "status": "accepted", "category": "marketing" },
    { "id": "em_01ky7q1vmkesyr1z1h4s48jjxm", "status": "accepted", "category": "transactional" }
  ]
}
Ogni figlio è un messaggio ordinario: traccialo tramite il suo ID em_ attraverso GET /v1/email/messages/{message_id}, i suoi endpoint per destinatari ed eventi e i webhook, esattamente come se lo avessi inviato singolarmente. Si applica lo stesso modello asincrono, quindi 202 significa accettato in modo durevole e gli esiti per destinatario arrivano successivamente.

Ripetizioni idempotenti

Invia un header Idempotency-Key con il batch, come fa la richiesta di esempio. Se la richiesta è riuscita ma non hai mai visto la risposta, ripetendola con la stessa chiave ottieni il risultato originale, gli stessi ID dei messaggi figli e un header Idempotency-Replay, invece di inviare di nuovo tutti i messaggi. Un duplicato accidentale qui ti costa fino a 100 email, quindi considera la chiave obbligatoria in produzione. Vedi idempotenza.

Allegati e limite del corpo

Ogni elemento del batch può avere i propri attachments, con lo stesso contratto di campo e budget di dimensione per messaggio di un invio singolo (vedi allegati). Un ulteriore limite si applica al batch nel suo insieme: il corpo della richiesta JSON serializzato è limitato a 20 MB, e un corpo più grande viene rifiutato con un 413. Gli allegati codificati in Base64 contano in quel limite, quindi i batch con molti allegati lo raggiungono rapidamente. Suddividili in più batch oppure inviali uno alla volta.

Broadcast

Un broadcast invia una sola email a un pubblico salvato. Risolviamo i membri attuali del pubblico, meno le soppressioni, nella lista dei destinatari al momento dell'invio, e le proprietà di contatto di ciascun destinatario compilano le variabili del template. Avviane uno dalla dashboard, da /v1/email/broadcasts o con i comandi bird email broadcasts. Broadcast contiene la guida passo passo.

Prossimi passi

  • Invio di email: il payload per elemento nel dettaglio, inclusi campi, limiti, tag e metadati a confronto
  • Broadcast: una sola email a un pubblico salvato, personalizzata per contatto
  • Categorie: marketing e transactional, e cosa comporta ciascuna per la politica di soppressione
  • Idempotenza: formato della chiave, conservazione e semantica di ripetizione
  • Riferimento API: gli schemi completi di richiesta e risposta del batch
  • Inviare 100 email con una singola chiamata API: un video che mostra un batch in uscita e come ogni messaggio restituisce il suo esito

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Esplora la funzionalitàEmail batch sendingSegui il percorso di apprendimentoBuild your first integration
Ottieni un brief di implementazione