Send in bulk
Send up to 10,000 messages in one request.
Use POST /messages/batch to send to many people at once. Every message in a batch uses the same sender ID. Each recipient gets the batch text unless you give them their own.
curl https://api.appstractone.com/v1/messages/batch \
-H "Authorization: Bearer $APPSTRACT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9b2e4c7a-1d3f-4e5a-8b6c-7d8e9f0a1b2c" \
-d '{
"from": "MYSHOP",
"text": "Our store opens at 9am tomorrow.",
"reference": "promo-november",
"recipients": [
{ "to": "0241234567" },
{ "to": "0201234567", "text": "Hi Ama, your order is ready." }
]
}'The response lists every accepted message and any recipient that was rejected:
{
"batchId": "bat_01M6MJSBW6TNFXDJ48HMRQXBPJ",
"status": "processing",
"test": false,
"accepted": 2,
"rejected": 0,
"segments": 2,
"cost": { "amount": "0.08", "currency": "GHS" },
"messages": [
{
"id": "msg_01M6MJSBW6TNFXDJ48HMRQXBPK",
"to": "+233241234567",
"status": "queued",
"encoding": "GSM-7",
"segments": 1,
"cost": { "amount": "0.04", "currency": "GHS" },
"reference": null,
"test": false
},
{
"id": "msg_01M6MJSBW6TNFXDJ48HMRQXBPM",
"to": "+233201234567",
"status": "queued",
"encoding": "GSM-7",
"segments": 1,
"cost": { "amount": "0.04", "currency": "GHS" },
"reference": null,
"test": false
}
],
"errors": []
}Rejected recipients, such as invalid numbers, appear in errors with a code and are not charged. The rest of the batch is still sent. If no recipient is valid, the request fails with 400 and the code no_valid_recipients.
Estimate a batch first
POST /messages/batch/estimate takes the same body, prices it and checks it against your balance without sending anything:
{
"accepted": 2,
"rejected": 0,
"segments": 2,
"totalCost": { "amount": "0.08", "currency": "GHS" },
"balance": { "amount": "19.96", "currency": "GHS" },
"sufficient": true,
"errors": []
}Know when a batch is done
Subscribe to the batch.completed webhook. It fires once every message in the batch has a final status, with counts of delivered and failed messages. You can also list a batch's messages with GET /messages?batchId=bat_....