> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hany.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Bulk SMS Messages to Multiple Recipients — /sms/bulk

> POST /sms/bulk sends personalized SMS messages to multiple recipients in a single API call. Returns a batch_id for tracking the campaign.

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.

<Note>
  All requests must include the `Authorization: Bearer YOUR_API_KEY` header. Requests and responses use `Content-Type: application/json`.
</Note>

## Endpoint

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

## Request

```bash theme={null}
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

<ParamField body="from" type="string" required>
  Your registered and approved Sender ID. This value is applied to every message in the batch. Maximum 11 alphanumeric characters.
</ParamField>

<ParamField body="messages" type="array" required>
  An array of message objects to send. Each object must include the following fields:

  <ParamField body="messages[].to" type="string" required>
    Recipient phone number in E.164 format (e.g. `+233201234567`).
  </ParamField>

  <ParamField body="messages[].message" type="string" required>
    The SMS message body for this recipient. Messages longer than 160 characters are split into segments; each segment consumes 1 credit.
  </ParamField>
</ParamField>

<ParamField body="callback_url" type="string">
  An HTTPS URL to receive delivery status webhook events for each individual message in the batch. The URL must be publicly reachable.
</ParamField>

## Response

### 200 — Success

```json theme={null}
{
  "status": "success",
  "batch_id": "batch_xyz789abc",
  "total": 3,
  "queued": 3,
  "credits_used": 3,
  "credits_remaining": 4997
}
```

## Response Fields

<ResponseField name="status" type="string">
  Indicates the outcome of the request. Either `"success"` or `"error"`.
</ResponseField>

<ResponseField name="batch_id" type="string">
  Unique identifier for this campaign batch. Use this value to filter delivery reports via the [Delivery Reports](/api-reference/sms/delivery-reports) endpoint.
</ResponseField>

<ResponseField name="total" type="integer">
  The total number of messages submitted in this request.
</ResponseField>

<ResponseField name="queued" type="integer">
  The number of messages successfully accepted and queued for delivery. If any messages failed validation, `queued` will be less than `total`.
</ResponseField>

<ResponseField name="credits_used" type="integer">
  The total number of credits consumed across all queued messages.
</ResponseField>

<ResponseField name="credits_remaining" type="integer">
  Your account's remaining credit balance after this bulk send.
</ResponseField>

## Tips and Limits

<Tip>
  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.
</Tip>

<Info>
  For campaigns exceeding 10,000 recipients, contact [Hany support](mailto:support@hany.tools) for optimized batch processing and dedicated throughput.
</Info>

## Code Examples

<CodeGroup>
  ```javascript JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  import requests

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

  response = requests.post(
      "https://api.hany.tools/v1/sms/bulk",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "from": "YourBrand",
          "messages": [
              {"to": r["to"], "message": f"Hi {r['name']}, your promo code is SAVE20"}
              for r in recipients
          ],
          "callback_url": "https://yourapp.com/webhooks/sms",
      },
  )

  data = response.json()
  print(data["batch_id"])   # "batch_xyz789abc"
  print(data["queued"])     # 3
  ```
</CodeGroup>