Send batch messages

Send batch messages

post

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.

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

channelIdstring · uuidRequired

The ID for a channel

Body

application/json

Array of messages to send to a channel. The batch can contain up to 100 messages.

Responses

202

Messages were accepted to be validated asynchronously and then processed.

application/json

400

The specified amount of messages in the batch is invalid.

application/json

404

The channel configuration was not found.

application/json

422

The request did not pass validation

application/json

post

/workspaces/{workspaceId}/channels/{channelId}/batch/messages

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/channels/{channelId}/batch/messages HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2740

{
  "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": {
          "disallowMmLite": 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"
        }
      },
      "replyTo": {
        "id": "text",
        "order": 1,
        "type": "message"
      },
      "body": {
        "type": "text",
        "text": {
          "text": "text",
          "attachments": [
            {
              "mediaUrl": "https://example.com",
              "filename": "text",
              "inline": true,
              "contentId": "text"
            }
          ],
          "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"
            },
            "apple": {
              "summaryText": "text"
            }
          }
        }
      },
      "notification": {
        "url": "text"
      },
      "capFrequency": true,
      "enableLinkTracking": true,
      "ignoreQuietHours": true,
      "ignoreGlobalHoldout": true,
      "tags": [
        "text"
      ],
      "shortLinks": {
        "domain": "text"
      },
      "scheduledFor": "2025-12-18T01:09:21.285Z",
      "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.

Request

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"
        }
    ]
}'

Response (200 - OK)

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.