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

MessageBird_userMessageBird_accessKey

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

channelIdstring · uuidRequired

The ID for a channel

Body

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

messageRequestsall of[] · min: 1Optional

Responses

application/json

objectOptional

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

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

{
  "messageRequests": [
    {
      "sender": {
        "connector": {
          "identifierValue": "[e-mail]",
          "annotations": {
            "name": "text"
          }
        }
      },
      "receiver": {
        "contacts": [
          {
            "id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
            "identifierKey": "emailaddress",
            "identifierValue": "[e-mail]",
            "type": "cc",
            "identifiers": [
              {
                "identifierKey": "emailaddress",
                "identifierValue": "[e-mail]"
              }
            ],
            "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"
          }
        ]
      },
      "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-04-22T04:53:26.424Z",
      "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": "[e-mail]"
                    }
                ]
            },
            "body": {
                "type": "text",
                "text": {
                    "text": "Hey, I am a simple text message"
                }
            }
        },
        {
            "receiver": {
                "contacts": [
                    {
                        "identifierValue": "[e-mail]"
                    }
                ]
            },
            "template": {
                "projectId": "4b7e08a9-5d0e-4e56-aaf1-cd0bfa29d431",
                "version": "fe72e43f-340e-4d41-9a9e-a136278ebb04",
                "locale": "en"
            }
        },
        {
            "receiver": {
                "contacts": [
                    {
                        "identifierValue": "[e-mail]"
                    }
                ]
            },
            "body": {
                "type": "text",
                "text": {
                    "text": "Hey, I am a scheduled message"
                }
            },
            "scheduledFor": "2024-11-26T15:00:00.000Z"
        }
    ]
}'

Response (200 - OK)

{
    "id": "70cc4cfa-0756-4ca7-8566-c8a83ee92af3",
    "messages": [
        {
            "id": "71d1c562-c8c8-4f03-89ff-2ed0026ea1ea"
        },
        {
            "id": "e75e3dd7-9429-4d9b-a006-c2eba19a1baa"
        },
        {
            "id": "3e7d1712-0fdb-476d-bf01-3d8ceb6a1d19"
        }
    ]
}

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.