Skip to main content
Use this endpoint to send a campaign to multiple recipients in one request. Each message in the batch can be individually personalized, making it ideal for promotional campaigns, transactional notifications, and appointment reminders at scale.
All requests must include the Authorization: Bearer YOUR_API_KEY header. Requests and responses use Content-Type: application/json.

​
Endpoint

POST https://api.hany.tools/v1/sms/bulk

​
Request

curl -X POST https://api.hany.tools/v1/sms/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "YourBrand",
    "messages": [
      { "to": "+233201234567", "message": "Hi Kwame, your promo code is SAVE20" },
      { "to": "+233209876543", "message": "Hi Ama, your promo code is SAVE20" },
      { "to": "+233241111222", "message": "Hi Kofi, your promo code is SAVE20" }
    ],
    "callback_url": "https://yourapp.com/webhooks/sms"
  }'

​
Request Body Parameters

​
from
string
required
Your registered and approved Sender ID. This value is applied to every message in the batch. Maximum 11 alphanumeric characters.
​
messages
array
required
An array of message objects to send. Each object must include the following fields:
​
messages[].to
string
required
Recipient phone number in E.164 format (e.g. +233201234567).
​
messages[].message
string
required
The SMS message body for this recipient. Messages longer than 160 characters are split into segments; each segment consumes 1 credit.
​
callback_url
string
An HTTPS URL to receive delivery status webhook events for each individual message in the batch. The URL must be publicly reachable.

​
Response

​
200 — Success

{
  "status": "success",
  "batch_id": "batch_xyz789abc",
  "total": 3,
  "queued": 3,
  "credits_used": 3,
  "credits_remaining": 4997
}

​
Response Fields

​
status
string
Indicates the outcome of the request. Either "success" or "error".
​
batch_id
string
Unique identifier for this campaign batch. Use this value to filter delivery reports via the Delivery Reports endpoint.
​
total
integer
The total number of messages submitted in this request.
​
queued
integer
The number of messages successfully accepted and queued for delivery. If any messages failed validation, queued will be less than total.
​
credits_used
integer
The total number of credits consumed across all queued messages.
​
credits_remaining
integer
Your account’s remaining credit balance after this bulk send.

​
Tips and Limits

Personalize each message in the messages array using the recipient’s name, account details, or any custom data relevant to them. Personalized messages consistently achieve higher engagement than generic broadcast copy.
For campaigns exceeding 10,000 recipients, contact Hany support for optimized batch processing and dedicated throughput.

​
Code Examples

const recipients = [
  { to: "+233201234567", name: "Kwame" },
  { to: "+233209876543", name: "Ama" },
  { to: "+233241111222", name: "Kofi" },
];

const response = await fetch("https://api.hany.tools/v1/sms/bulk", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "YourBrand",
    messages: recipients.map(({ to, name }) => ({
      to,
      message: `Hi ${name}, your promo code is SAVE20`,
    })),
    callback_url: "https://yourapp.com/webhooks/sms",
  }),
});

const data = await response.json();
console.log(data.batch_id);    // "batch_xyz789abc"
console.log(data.queued);      // 3