Ping
API Docs

Send Bulk SMS

Send SMS messages to multiple recipients simultaneously. The bulk SMS API allows you to send the same message to hundreds or thousands of recipients efficiently with tracking and status reporting.

Headers

  • Authorization: Bearer YOUR_API_KEY
  • Content-Type: application/json

Body Parameters

recipients

Required - Array of phone numbers in international format (e.g., ["+263771234567", "+263777654321"]).

message

Required - The SMS message content (max 160 characters for single SMS).

sender_id

Optional - Custom sender ID (default: "PING"). Must be approved for custom sender IDs.

provider

Optional - SMS provider to use ("twilio", "africastalking"). System auto-selects if not specified.

name

Optional - Name for this bulk operation for tracking purposes.

Sample Requests

curl -X POST https://api.ping.co.zw/v1/notification/api/sms/bulk \
-H "Authorization: Bearer sk_test_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
  "recipients": [
    "+263771234567",
    "+263777654321",
    "+263712345678",
    "+263787654321"
  ],
  "message": "Important: Your appointment is scheduled for tomorrow at 2 PM. Please confirm.",
  "sender_id": "CLINIC",
  "name": "Appointment Reminders - Dec 2024"
}'

Response Format

Success Response

{
  "result": "success",
  "message": "Sending SMS to 4 recipients in background",
  "environment": "test",
  "bulkId": "bulk_uuid_here",
  "totalRecipients": 4
}

Error Response

{
  "result": "error",
  "error": {
    "type": "BadRequest",
    "message": "Invalid phone number format: +invalid-number"
  }
}

Bulk Operation Tracking

Once you initiate a bulk SMS operation, you'll receive a bulkId that you can use to track the progress and status of your bulk operation.

Check Bulk Status

curl -X GET https://api.ping.co.zw/v1/notification/api/bulk/{bulkId} \
-H "Authorization: Bearer sk_test_your_api_key_here"

Bulk Status Response

{
  "result": "success",
  "bulk": {
    "id": "bulk_uuid_here",
    "name": "Appointment Reminders - Dec 2024",
    "type": "sms",
    "status": "completed",
    "totalRecipients": 4,
    "successCount": 3,
    "failureCount": 1,
    "startTime": "2024-01-15T10:00:00Z",
    "endTime": "2024-01-15T10:02:00Z",
    "dateCreated": "2024-01-15T10:00:00Z"
  }
}

Bulk SMS Limits

  • Maximum recipients per bulk operation: 10,000
  • Maximum concurrent bulk operations: 10 per account
  • Message length: 160 characters for single SMS, longer messages are split
  • Rate limit: 1000 SMS per minute per API key

Bulk Status Values

  • pending - Bulk operation is queued and waiting to start
  • processing - Messages are being sent
  • completed - All messages have been processed
  • failed - Bulk operation failed to complete
  • cancelled - Bulk operation was cancelled

Best Practices

  • Validate phone numbers before sending to reduce failures
  • Use meaningful names for bulk operations for easier tracking
  • Monitor bulk status regularly for large operations
  • Consider time zones when scheduling bulk messages
  • Test with small batches before sending to large lists

Error Handling

Individual message failures within a bulk operation don't cause the entire operation to fail. The API will attempt to send to all recipients and provide detailed success/failure counts.

Common Failure Reasons

  • Invalid phone number format
  • Blocked or inactive phone numbers
  • Network issues with SMS provider
  • Insufficient account balance (if applicable)
  • Spam filtering by recipient carrier