# Bulk & Campaign Messaging
URL: /docs/guides/bulk-campaigns

> Submit asynchronous high-volume broadcast jobs, schedule future campaigns, and poll batch delivery progress.

For promotional broadcasts, billing reminders, or announcements exceeding 10 recipients, submit asynchronous batch jobs to `POST /api/v1/public/sms/bulk/jobs`.

## Submitting a Bulk Job [#submitting-a-bulk-job]

You can supply either an explicit `recipients` array, pre-saved contact `groupIds`, or a pre-uploaded CSV/Excel `fileId`:

```json title="POST /api/v1/public/sms/bulk/jobs"
{
  "jobName": "November Promo Campaign",
  "senderId": "SMSPRO",
  "message": "Special offer! Use code PROMO50 today.",
  "recipients": ["+233241234567", "+233501234567"],
  "scheduledAt": "2026-11-20T09:00:00Z",
  "deliveryCallbackUrl": "https://myapp.com/webhooks/dlr"
}
```

SMS Pro immediately validates the payload, reserves units, and returns HTTP `202 Accepted` with a `batchId` (`batch-7f9a2e41-0023`) and `status: "QUEUED"`.

## Tracking Batch Progress [#tracking-batch-progress]

Poll `GET /api/v1/public/sms/bulk/jobs/{batchId}` to monitor throughput and completion:

```json title="Batch progress response"
{
  "batchId": "batch-7f9a2e41-0023",
  "jobName": "November Promo Campaign",
  "recipientCount": 2500,
  "status": "PROCESSING",
  "progressPercent": 78,
  "sentCount": 1950,
  "failedCount": 12,
  "totalUnits": 2500
}
```

## Managing Scheduled & Running Jobs [#managing-scheduled--running-jobs]

- **List scheduled messages:** `GET /api/v1/public/sms/scheduled`
- **Cancel a scheduled broadcast:** `PATCH /api/v1/public/sms/scheduled/{id}`
- **Cancel an in-flight bulk job:** `PATCH /api/v1/public/sms/bulk/jobs/{jobId}`
- **Inspect campaign summaries:** `GET /api/v1/public/sms/campaigns`