POST - Batch send
Sends messages to multiple recipients in a single API request. You will need to prepare a CSV file and upload it to this endpoint.
POST /campaigns/:campaignId/batch/messagesPath Parameters
campaignId
string
Yes
The ID of the campaign to send messages through. Found in the Postman admin portal after creating a campaign.
Request Headers
Authorization
Bearer YOUR_API_KEY
Yes
Content-Type
multipart/form-data
Yes
Request Body
Upload your CSV file as a multipart/form-data request. The form field name must be file.
CSV format
The CSV must include recipient and language as the first two columns, followed by columns for each template parameter defined in the campaign's message template.
recipient,language,recipient_name,topic
6599999999,english,Emily Yeo,passport application #12345F
6599999998,chinese,James Tan,passport application #67890ACSV requirements
Header row
Must match the template parameter names exactly (lowercase letters, numbers, and _ only).
recipient column
Phone number with country code, without the + prefix. E.g. 6591234567.
language column
Must be one of: english, chinese, malay, tamil. Must match a language configured for the campaign.
Template parameters
All template parameters must be filled for every row.
Max file size
40 MB.
Test environment limit
20 rows maximum if you are in the test environment.
Row errors
Any errors in the CSV rows will cause the entire file upload to fail. You must fix all errors before uploading again.
Using a single {{body}} variable
If you manage message templates within your own system, you may use a single {{body}} variable.
Line breaks in CSV
Use keyboard line breaks directly within the CSV cell (not \n). Excel will automatically wrap the content in double quotes when saving as CSV.
Do not manually add double quotes around the {{body}} value if you are using Excel, as Excel adds them automatically when saving as CSV.
Response
HTTP 201 Created
Returns a validation result with the batch ID.
isValid
boolean
Whether the CSV was valid and the batch was created.
batchId
string
The unique batch ID. Use this to query the Retrieve Batch Messages endpoint or the Retry Batch Send endpoint.
Error Responses
HTTP 400 Bad Request
parameter_invalid
File too large, max file size is 40MB
CSV file exceeds the 40 MB size limit.
parameter_invalid
Validation failed (expected type is object)
CSV headers do not match the campaign's template parameters, or required columns are missing.
HTTP 401 Unauthorized
invalid_api_key_provided
The API key provided is invalid.
API key is incorrect, expired, or deleted.
invalid_ip_address_error
The IP address used for this request is invalid.
Request sent from a non-whitelisted IP address.
HTTP 429 Too Many Requests
too_many_requests
Too many requests
Rate limit exceeded. Default is 10 TPS per campaign, shared across all endpoints. Implement exponential backoff and retry.
Example: cURL
Notes
If your campaign sends more than 200,000 recipients or makes more than 50 API requests per second (or more than 100 message segments per second), you must submit the large campaign form to ensure other large campaigns are not also happening on the same day. Otherwise, delivery for all campaigns will be affected.
For batch send, 1 TPS = 1 API call = multiple messages. If your CSV has 20 rows, one API call sends 20 messages. This differs from single send, where 1 TPS = 1 API call = 1 message.
OTP messages should always use Single Send.
The response confirms the batch was created, but does not indicate delivery status. Use the Retrieve Batch Messages endpoint to check the delivery status of individual messages in the batch.
To retry failed messages in a batch, use the Retry Batch Send endpoint.
Last updated
Was this helpful?