Send batch messages
The send batch messages endpoint allows sending a batch up to 100 messages to a channel. The messages are accepted for validation and processed asynchronously. Messages that fail validation are rejected, and the failure is attached to the message. The response will return a batch ID which can be used to retrieve the messages that were in the batch.
The ID of the workspace
The ID for a channel
Array of messages to send to a channel. The batch can contain up to 100 messages.
POST /workspaces/{workspaceId}/channels/{channelId}/batch/messages HTTP/1.1
Host: api.bird.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 2737
{
"messageRequests": [
{
"sender": {
"connector": {
"identifierValue": "[email protected]",
"annotations": {
"name": "text"
}
}
},
"receiver": {
"contacts": [
{
"id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"type": "cc",
"identifiers": [
{
"identifierKey": "emailaddress",
"identifierValue": "[email protected]"
}
],
"platformAddress": "text",
"platformAddressSelector": "text"
}
]
},
"reference": "my-own-identifier",
"template": {
"name": "text",
"projectId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"version": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"locale": "text",
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text",
"inline": true
}
],
"shortLinks": {
"enabled": true,
"domain": "text"
},
"variables": {
"default": "text",
"ANY_ADDITIONAL_PROPERTY": "text"
},
"utmParameters": [
{
"key": "text",
"value": "text"
}
],
"parameters": [
{
"type": "string",
"key": "text",
"value": "text"
}
],
"settings": {
"useMmLite": true
}
},
"meta": {
"extraInformation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"referral": {
"source": "text",
"title": "text",
"text": "text",
"group": "text",
"metadata": {
"source_id": "text",
"source_url": "text",
"media_url": "text",
"tracking_id": "text"
}
},
"order": {
"products": [
{
"externalCatalogId": "text",
"externalProductId": "text",
"quantity": 1,
"price": {
"amount": 1,
"exponent": 1,
"currencyCode": "text"
}
}
]
},
"referredProduct": {
"externalCatalogId": "text",
"externalProductId": "text"
},
"email": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"from": {
"username": "text",
"displayName": "text"
}
},
"pushNotifications": {
"gatewayTypeOverride": "apns"
},
"navigatorId": "123e4567-e89b-12d3-a456-426614174000",
"navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
"flow": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"stepId": "text",
"runId": "123e4567-e89b-12d3-a456-426614174000"
},
"journey": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"stepId": "text",
"runId": "123e4567-e89b-12d3-a456-426614174000"
},
"campaign": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text"
},
"skipThisMessage": "globalHoldout"
},
"replyTo": {
"id": "text",
"order": 1,
"type": "message"
},
"body": {
"type": "text",
"text": {
"text": "text",
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text",
"inline": true
}
],
"actions": [
{
"type": "link",
"link": {
"text": "text",
"url": "text"
}
}
],
"metadata": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"whatsapp": {
"previewUrl": true
},
"line": {
"emoji": {
"items": [
{
"index": 1,
"productId": "text",
"emojiId": "text"
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
},
"notification": {
"url": "text",
"template": "text"
},
"capFrequency": true,
"enableLinkTracking": true,
"ignoreQuietHours": true,
"ignoreGlobalHoldout": true,
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-06-22T23:40:44.725Z",
"validity": 1
}
]
}{
"id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"messages": [
{
"id": "a1405560-c8d3-4b1a-877d-3f449ad95352"
}
]
}Examples
Let's establish some of our data that will be used in the following examples:
Workspace ID: a1405560-c8d3-4b1a-877d-3f449ad95352
AccessKey: abcd
Channel ID: a1405560-c8d3-4b1a-877d-3f449ad95352
Send batch of messages
In this example, we're sending multiple SMS messages to different receivers using variations of content.
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/channels/a1405560-c8d3-4b1a-877d-3f449ad95352/batch/messages" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"messageRequests": [
{
"receiver": {
"contacts": [
{
"identifierValue": "[email protected]"
}
]
},
"body": {
"type": "text",
"text": {
"text": "Hey, I am a simple text message"
}
}
},
{
"receiver": {
"contacts": [
{
"identifierValue": "[email protected]"
}
]
},
"template": {
"projectId": "4b7e08a9-5d0e-4e56-aaf1-cd0bfa29d431",
"version": "fe72e43f-340e-4d41-9a9e-a136278ebb04",
"locale": "en"
}
},
{
"receiver": {
"contacts": [
{
"identifierValue": "[email protected]"
}
]
},
"body": {
"type": "text",
"text": {
"text": "Hey, I am a scheduled message"
}
},
"scheduledFor": "2024-11-26T15:00:00.000Z"
}
]
}'Batch messages can be monitored using Retrieving messages endpoints by providing the batchID returned in the response. This allows you to check if any messages within the batch failed. Messages with a rejected status will emit events, containing detailed failure codes, enabling you to identify and address issues efficiently. For more details on how to subscribe to these events, refer to the Notifications API documentation.
Last updated
Was this helpful?