Ping

Bulk Operations

Send SMS, WhatsApp, and email notifications to hundreds or thousands of recipients efficiently using bulk operations. Track job progress and delivery status in real-time.

Bulk notifications

Bulk operations allow you to send the same message to multiple recipients in a single API call. The Ping API processes bulk jobs in the background and provides job tracking.

How bulk sending works

  1. Submit bulk job - Send array of recipients or recipient group ID
  2. Job processing - Messages sent asynchronously in background
  3. Track progress - Poll job status to monitor delivery
  4. View results - See successful deliveries and failures

Bulk SMS

Send SMS to multiple recipients using the same endpoint as single SMS, but provide an array of phone numbers or a recipient group ID.

Endpoint: POST /v1/notification/api/sms/send

Request with array:

{
  "to_phone": ["+263771234567", "+263772345678", "+263773456789"],
  "message": "Your appointment is tomorrow at 2pm"
}

Request with recipient group:

{
  "recipient_group_id": "group-uuid-here",
  "message": "Your appointment is tomorrow at 2pm"
}

Bulk WhatsApp

Send WhatsApp messages to multiple recipients.

Endpoint: POST /v1/notification/api/whatsapp/send

Request:

{
  "to_phone": ["+263771234567", "+263772345678"],
  "message": "Your order has been shipped!"
}

Bulk Email

Send emails to multiple recipients.

Endpoint: POST /v1/notification/api/email/send

Request:

{
  "from": "[email protected]",
  "to": ["[email protected]", "[email protected]"],
  "subject": "Weekly Newsletter",
  "html": "<h1>This Week's Updates</h1><p>...</p>"
}

Performance Tips:

  • Bulk jobs process ~80-100 messages per second
  • Large jobs (1000+ recipients) may take several minutes
  • Use recipient groups for repeated bulk sends
  • Check billing balance before large bulk operations

Response format

Bulk job response

{
  "result": "success",
  "message": "Sending SMS to 500 recipients in background",
  "bulk_id": "bulk-uuid-here",
  "total_recipients": 500,
  "billing": {
    "cost": 25.00,
    "currency": "USD",
    "provider": "econet"
  }
}
GET/v1/notification/api/bulk/:bulk_id

Get bulk job status

Retrieve the current status and statistics for a bulk notification job.

Required headers

  • Name
    X-Ping-Api-Key
    Type
    string
    Description

    Your API key (for API key auth).

Or use JWT authentication:

  • Name
    Authorization
    Type
    string
    Description

    Bearer token.

  • Name
    User-Type
    Type
    string
    Description

    Must be user, adminuser, or agent.

Request

GET
/v1/notification/api/bulk/{bulk_id}
curl https://api.ping.co.zw/v1/notification/api/bulk/bulk-abc123 \
  -H "X-Ping-Api-Key: pk_live_your_api_key"

Response

{
  "result": "success",
  "bulk_job": {
    "public_id": "bulk-abc123",
    "name": "SMS to 500 recipients",
    "type": "sms",
    "status": "processing",
    "total_recipients": 500,
    "sent_count": 342,
    "delivered_count": 310,
    "failed_count": 12,
    "start_time": "2025-01-15T10:00:00Z",
    "end_time": null,
    "created_by": "user-uuid",
    "business_id": 1
  }
}
GET/v1/notification/api/bulk

List bulk jobs

Retrieve a paginated list of all bulk notification jobs for your account.

Required headers

  • Name
    X-Ping-Api-Key
    Type
    string
    Description

    Your API key (for API key auth).

Or use JWT authentication with Authorization and User-Type headers.

Optional parameters

  • Name
    skip
    Type
    integer
    Description

    Number of records to skip (default: 0).

  • Name
    limit
    Type
    integer
    Description

    Maximum number of records to return (default: 50).

  • Name
    status
    Type
    string
    Description

    Filter by status: processing, completed, failed.

Request

GET
/v1/notification/api/bulk
curl -G https://api.ping.co.zw/v1/notification/api/bulk \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -d limit=10 \
  -d status=completed

Response

{
  "result": "success",
  "bulk_jobs": [
    {
      "public_id": "bulk-abc123",
      "name": "SMS to 500 recipients",
      "type": "sms",
      "status": "completed",
      "total_recipients": 500,
      "sent_count": 500,
      "delivered_count": 485,
      "failed_count": 15,
      "start_time": "2025-01-15T10:00:00Z",
      "end_time": "2025-01-15T10:06:20Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Job status values

Status lifecycle

Bulk jobs progress through these statuses:

  • Name
    processing
    Description

    Job is actively sending messages. Check sent_count for progress.

  • Name
    completed
    Description

    All messages have been processed (successfully or failed). Check delivered_count and failed_count for final results.

  • Name
    failed
    Description

    Job failed to start or encountered a critical error. Check error message.

  • Name
    cancelled
    Description

    Job was manually cancelled before completion.

Monitoring progress

Poll the job status endpoint every 5-10 seconds while status is processing:

import time

while True:
    job = get_bulk_job(bulk_id)
    if job['status'] != 'processing':
        break
    print(f"Progress: {job['sent_count']}/{job['total_recipients']}")
    time.sleep(5)

print(f"Final: {job['delivered_count']} delivered, {job['failed_count']} failed")

Best Practices:

  • Don't poll faster than every 5 seconds
  • Implement exponential backoff for long jobs
  • Set a maximum polling duration (e.g., 30 minutes)
  • Store bulk_id for later reference
  • Check billing balance before large sends

Was this page helpful?