Envoi par lot

POST /v1/email/batches accepte jusqu'à 100 payloads d'envoi complets en une seule requête. Chaque élément est un message indépendant avec son propre expéditeur, ses destinataires et son contenu. Utilisez un lot pour soumettre des reçus, des alertes ou d'autres messages par destinataire avec moins de requêtes API. Pour un seul message, consultez Envoyer un e-mail.

Quand utiliser quoi

Des messages indépendants que vous avez déjà en main. Utilisez un lot et transmettez-les en une seule requête.
Un flux soutenu à haut volume. Appeler le endpoint d'envoi unique en boucle est une architecture valable, et un lot ne rend aucun message individuel moins cher ni plus rapide à livrer. Ce qu'il change, c'est le débit, car les requêtes par lot utilisent le groupe de limitation du débit email_batch plutôt que le groupe email_send, et chacune prend en charge jusqu'à 100 messages.
Un seul e-mail à une audience enregistrée. Il s'agit d'un broadcast, qui résout l'audience en destinataires et personnalise le message par contact.

Envois par lot

Le corps de la requête est un objet JSON dont le tableau messages contient de 1 à 100 objets message. Chaque élément est une requête d'envoi complète et indépendante avec ses propres from, to, subject, contenu, et éventuellement ses propres category, ip_pool_id, tags et métadonnées. Le schéma de l'élément est exactement le payload d'envoi unique, donc tout ce qui est décrit dans envoyer un e-mail s'applique par élément, y compris la valeur par défaut category de marketing et l'envoi par template.

Cela inclut scheduled_at, de sorte qu'un lot peut mélanger des messages envoyés immédiatement avec des messages envoyés plus tard, chacun à son propre moment. Les règles et le quota décrits dans envoi planifié s'appliquent par élément, et un élément planifié est annulé par son propre ID comme tout autre message planifié.

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."
    }
  ]
}
JSON

curl -X POST https://us1.platform.bird.com/v1/email/batches \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-2026-07-23-001" \
  -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"
      }
    ]
  }'

Validation en tout ou rien

Chaque élément est validé avant qu'aucun élément ne soit mis en file d'attente. Si un message échoue, qu'il s'agisse d'une erreur de validation au niveau d'un champ ou d'un domaine d'expéditeur non vérifié, le lot entier est rejeté avec une 422 et rien n'est envoyé : corrigez cet élément et soumettez à nouveau le lot.

La suppression ne fait pas partie de cette vérification. Un élément dont tous les destinataires sont supprimés est tout de même accepté et reçoit son propre ID em_, et ces destinataires reviennent comme status: rejected une fois le message traité (voir suppressions).

Traiter la réponse 202

Un lot réussi renvoie 202 Accepted avec une entrée par message, dans l'ordre de soumission :

Exemple de code

{
  "data": [
    { "id": "em_01ky7q1vmkerwa7fxyycfe5ks1", "status": "accepted", "category": "transactional" },
    { "id": "em_01ky7q1vmkesr9h1y52tkqng9f", "status": "accepted", "category": "marketing" },
    { "id": "em_01ky7q1vmkesyr1z1h4s48jjxm", "status": "accepted", "category": "transactional" }
  ]
}

Chaque enfant est un message ordinaire : suivez-le par son ID em_ via GET /v1/email/messages/{message_id}, ses endpoints de destinataire et d'événement, et les webhooks, exactement comme si vous l'aviez envoyé seul. Le même modèle asynchrone s'applique, donc 202 signifie accepté de manière durable et les résultats par destinataire arrivent ensuite.

Réessais idempotents

Envoyez un en-tête Idempotency-Key avec le lot, comme le fait la requête d'exemple. Si la requête a réussi mais que vous n'avez jamais vu la réponse, la rejouer avec la même clé renvoie le résultat original, les mêmes ID de messages enfants et un en-tête Idempotency-Replay, au lieu de renvoyer chaque message. Un doublon accidentel ici vous coûte jusqu'à 100 e-mails, alors considérez la clé comme obligatoire en production. Voir idempotence.

Pièces jointes et limite de taille du corps

Chaque élément du lot peut avoir ses propres attachments, selon le même contrat de champ et le même budget de taille par message qu'un envoi unique (voir pièces jointes). Une limite supplémentaire s'applique au lot dans son ensemble : le corps de requête JSON sérialisé est plafonné à 20 Mo, et un corps plus volumineux est rejeté avec une 413. Les pièces jointes encodées en Base64 comptent dans cette limite, donc les lots contenant beaucoup de pièces jointes l'atteignent rapidement. Répartissez-les sur plusieurs lots, ou envoyez-les un par un.

Broadcasts

Un broadcast envoie un e-mail à une audience enregistrée. L'audience est résolue en liste de destinataires à partir de ses membres actuels, moins les suppressions, au moment du lancement de l'envoi, et les propriétés de contact de chaque destinataire remplissent les variables du template. Lancez-en un depuis le tableau de bord, depuis /v1/email/broadcasts, ou avec les commandes bird email broadcasts. Broadcasts contient le guide pas à pas.

Étapes suivantes

Envoyer un e-mail : le payload par élément en détail, y compris les champs, les limites, et tags vs métadonnées
Broadcasts : un e-mail à une audience enregistrée, personnalisé par contact
Catégories : marketing et transactional, et l'effet de chacune sur la politique de suppression
Idempotence : format de clé, rétention et sémantique de rejeu
Référence API : les schémas complets de requête et de réponse du lot
Envoyer 100 emails en un seul appel API : une vidéo qui montre un lot envoyé et comment chaque message remonte son statut

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Explorer la fonctionnalitéEmail batch sending Suivre le parcours d'apprentissageBuild your first integration

Obtenir un guide d'implémentation