Create a batch of email messages

POST

/v1/email/batches

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 $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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."
      }
    ]
  }'

Antwort202

{
  "data": [
    {
      "id": "em_01krdgeqcxet5s7t44vh8rt9mg",
      "status": "accepted",
      "category": "marketing",
      "requested_language": "pt-BR",
      "resolved_language": "pt-BR",
      "template_id": "emt_01krdgeqcxet5s7t44vh8rt9mg",
      "template_version_id": "emv_01krdgeqcxet5s7t44vh8rt9mg"
    },
    {
      "id": "em_01krdgeqcxet5s7t44vh8rt9mh",
      "status": "accepted",
      "category": "transactional",
      "scheduled_at": "2026-05-22T09:00:00Z"
    }
  ]
}

Accepts up to 100 independent email messages and queues them for delivery. All items are validated before any are queued: if one fails validation, the entire batch is rejected. Field-level validation failures and business-rule failures, such as sending from a domain that is not verified, both return 422. An item can set scheduled_at to send it later, on the same terms as a single scheduled send, and one batch can mix scheduled and immediate messages. Cancel a scheduled item before it sends with Cancel an email message. Suppression is evaluated per recipient after acceptance, never as a synchronous error. The 202 response returns one entry per message in submission order, each with its own id you can use to fetch that message or match it against webhook events. Attachments are allowed per message. Each message must stay within the 20 MB estimated generated message-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap.

Anfrage-Nutzlast

messages

array of object

erforderlich

Email message send requests, up to 100. All items are validated before any are queued. Attachments are allowed on individual messages. Each message must stay within the 20 MB estimated generated message-size cap. The serialized JSON request body for the batch has a hard 20 MB cap.

Untergeordnete Parameter anzeigen

messages.from

string or object

erforderlich

Sender address, as a plain email string, an RFC 5322 mailbox string (Jane <jane@acme.com>), or an object with an optional display name. Must be from a verified domain in this workspace.

Untergeordnete Parameter anzeigen

messages.to

array of string or object

erforderlich

Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (Jane <jane@acme.com>), or an object with an optional display name.

Untergeordnete Parameter anzeigen

messages.cc

array of string or object

CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (Jane <jane@acme.com>), or an object with an optional display name.

Untergeordnete Parameter anzeigen

messages.bcc

array of string or object

BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (Jane <jane@acme.com>), or an object with an optional display name.

Untergeordnete Parameter anzeigen

messages.subject

string

Message subject line. Required for inline sends. Omit it when sending a template (the template supplies the subject).

messages.html

string

HTML body. At least one of html or text must be provided.

messages.text

string

Plain-text body. At least one of html or text must be provided.

messages.reply_to

array of string or object

Reply-To addresses, each a plain email string, an RFC 5322 mailbox string, or an object with an optional display name. RFC 5322 allows multiple. Every recipient reply hits all listed addresses, so 1-2 is typical. The 25 cap exists to prevent header sizes that some receiving mail servers reject.

Untergeordnete Parameter anzeigen

messages.headers

object

Custom email headers, such as References, In-Reply-To, and X-* headers. Reserved headers and values containing carriage returns or line feeds return 422. Set addressing and subject through their dedicated fields. Transactional sends accept List-Unsubscribe and List-Unsubscribe-Post. Marketing sends use Bird-managed unsubscribe by default.

messages.tags

array of object

Structured {name, value} labels for filtering and analytics. Tags become first-class query dimensions:

Filter the list endpoint by tag name.
Slice analytics rollups by tag.
Surface in webhook payloads.

Cap: 20 tags per send. Use tags for low-cardinality dimensions (category, experiment_variant, template_id). For arbitrary structured context that you do not need as a filter dimension, use metadata instead.

Untergeordnete Parameter anzeigen

messages.metadata

object

Arbitrary JSON object returned on API reads and included in webhook payloads. You can query its paths in analytics, such as metadata.order_id, but it is not a dashboard filter. The serialized object is limited to 2 KB. Use metadata for per-send context such as order IDs, customer references, and structured event data. For low-cardinality filterable labels, use tags instead.

messages.parameters

object

Parameter values used to personalize inline content, shared across all recipients of this send. Tokens such as {{ animal }} are replaced with matching values; missing values render empty. Include this object, even as {}, to use Liquid, or omit it to leave tokens unchanged. Use single-word names other than bird. Cap: 16 KB serialized. For a stored template, use template.parameters instead. See inline personalization for validation and URL encoding examples.

messages.template

object

Send a stored template instead of inline content. When set, omit subject, html and text, because the template supplies them. Personalize with template.parameters. Add scheduled_at to send it later.

Untergeordnete Parameter anzeigen

messages.track_opens

boolean

Whether to track open events for this message.

messages.track_clicks

boolean

Whether to track click events for this message.

messages.ip_pool_id

string

ID of the IP pool to send from (ipp_ prefix), or ipp_shared to route through the shared pool explicitly. Omit to use your organization's default pool. An unknown pool, or a pool with no dedicated IPs available to send from, is rejected with a 422.

messages.category

string

Content classification, which controls suppression policy:

marketing: Blocks on all suppression reasons.
transactional: Allows delivery through complaint and unsubscribe suppressions, for receipts, password resets, and similar operational mail.

When you send with template and omit this field, the message takes the template's own classification, so a template created as transactional sends as transactional. Set this field to classify a single send differently from its template. It always takes precedence. A send with no template and no category defaults to marketing.

Possible values: marketing, transactional

messages.attachments

array of object

Files to attach, up to 20 per message. A message can be at most 20 MB once it has been generated, and we refuse a send that would go over. That figure covers the HTML body, the text body and every attachment and inline image, all measured after base64 encoding, which adds roughly a third. So 15 MB of raw files already accounts for most of the budget, and the body competes for the same space. A batch send is held to the same 20 MB per message, and the whole request body is capped at 20 MB as well.

Untergeordnete Parameter anzeigen

messages.attachments.filename

string

erforderlich

The name the recipient sees on the attachment.

messages.attachments.content

string

erforderlich

Base64-encoded file bytes. The encoded value and MIME wrapping count toward the 20 MB message limit.

messages.attachments.content_type

string

The file's MIME type. If omitted, the API infers it from the extension in filename. The API rejects executable and script types based on this value.

messages.attachments.content_id

string

An RFC 2392 Content-ID for an inline file. Reference it from the HTML body with <img src="cid:{content_id}"/>. Omit it to send a downloadable attachment.

messages.scheduled_at

string

Schedule the message to send at a future time instead of immediately. Must be at least 30 seconds and at most 30 days ahead. Outside that range the request is rejected with 422. The message returns with status accepted and shows as scheduled on reads until it sends. Cancel it before then with the message cancel endpoint. Scheduled sends count against your plan's monthly scheduled-email allowance. Exceeding it is rejected with a 422. For a stored template, the published version, language and parameter values are pinned when we accept the request, so a later publication does not change what sends. If the template is deleted before the message is due, the message is rejected with generation_failure. We also check sender eligibility and send-volume allowance when the message is due. Batch items take this field too, so one batch can mix scheduled and immediate messages.

Antwort-Payload

data

array of object

erforderlich

One entry per message in the batch, in submission order.

Untergeordnete Attribute anzeigen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Implementierungs-Briefing erhalten

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 $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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."
      }
    ]
  }'

Antwort202

{
  "data": [
    {
      "id": "em_01krdgeqcxet5s7t44vh8rt9mg",
      "status": "accepted",
      "category": "marketing",
      "requested_language": "pt-BR",
      "resolved_language": "pt-BR",
      "template_id": "emt_01krdgeqcxet5s7t44vh8rt9mg",
      "template_version_id": "emv_01krdgeqcxet5s7t44vh8rt9mg"
    },
    {
      "id": "em_01krdgeqcxet5s7t44vh8rt9mh",
      "status": "accepted",
      "category": "transactional",
      "scheduled_at": "2026-05-22T09:00:00Z"
    }
  ]
}

Create a batch of email messages

Anfrage-Nutzlast

Antwort-Payload

Verwandte Ressourcen