Skip to Content

Bulk & Campaign Messaging

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

View Markdown (.md)

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

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

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

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

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

  • 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

On this page