> ## 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.

# Run Bulk SMS Campaigns to Thousands of Recipients Fast

> Send personalized SMS campaigns to hundreds or thousands of recipients at once. Hany handles delivery, tracking, and reporting automatically.

A Hany SMS campaign lets you send messages to a large list of recipients in a single API call. Each message in a campaign can be individually personalized — giving you the reach of bulk messaging with the feel of a one-to-one conversation. Hany queues, delivers, and tracks every message automatically so you can focus on your content, not your infrastructure.

## When to Use Campaigns

Campaigns are ideal whenever you need to reach many people at once with targeted, timely content:

* **Promotions & Offers** — Announce discounts, flash sales, or exclusive deals to your customer list.
* **Product Launches** — Notify subscribers the moment something new goes live.
* **Event Reminders** — Send automated reminders for webinars, appointments, or in-person events.
* **Newsletters & Updates** — Keep your audience informed with regular company or product news.
* **Service Alerts** — Broadcast scheduled maintenance windows, outage notices, or important policy changes.

## Send a Bulk Campaign

Use the `/v1/sms/bulk` endpoint to send a campaign. Pass an array of recipient objects — each with its own `to` and `message` fields — along with your Sender ID.

```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": "+233XXXXXXXXX", "message": "Hi John, your offer is ready!" },
      { "to": "+233YYYYYYYYY", "message": "Hi Jane, your offer is ready!" }
    ],
    "callback_url": "https://yourapp.com/webhooks/sms"
  }'
```

**Successful response:**

```json theme={null}
{
  "status": "success",
  "batch_id": "batch_xyz789",
  "total": 2,
  "queued": 2,
  "credits_used": 2,
  "credits_remaining": 4998
}
```

The `batch_id` uniquely identifies your campaign. Use it to retrieve delivery reports for the entire batch.

## Personalization

Because each entry in the `messages` array is its own object, you can fully customize the content for every recipient. Merge in first names, account details, order numbers, expiry dates — anything that makes your message feel personal.

```json theme={null}
{
  "from": "ShopNow",
  "messages": [
    {
      "to": "+233XXXXXXXXX",
      "message": "Hi Kwame, your loyalty points expire on Jan 31. Redeem them now at shopnow.com/rewards"
    },
    {
      "to": "+233YYYYYYYYY",
      "message": "Hi Abena, you have GHS 50 store credit waiting. Use code ABENA50 at checkout."
    }
  ]
}
```

Build the `messages` array dynamically in your application by iterating over your contacts list and interpolating each recipient's data before making the API request.

## Campaign Limits

<Info>
  There is no hard cap on standard campaign sizes. For very large sends — 100,000 recipients or more — contact the Hany support team before dispatching. The team can help you schedule your campaign during optimal delivery windows, ensure your account has sufficient credits, and provide dedicated throughput for time-sensitive blasts.
</Info>

## Tracking Campaign Delivery

After you dispatch a campaign, Hany tracks the delivery status of every message in the batch. You have two ways to monitor results:

* **Dashboard** — Go to **SMS → Campaigns** and select your batch by its `batch_id` to see a real-time breakdown of delivered, pending, and failed messages.
* **Webhooks** — Add a `callback_url` field at the top level of your request body. Hany will `POST` a delivery update to that URL whenever the status of any message in the batch changes.

For full webhook payload details and delivery status codes, see the Delivery Reports documentation.

<Tip>
  Before sending to your full contact list, always run a test campaign with a small batch of internal numbers. This lets you verify message content, confirm your Sender ID is working, and check that any personalization tokens are rendering correctly.
</Tip>