Bulk Status

Check the status and progress of your bulk notification operations. Get detailed information about success/failure counts, timing, and individual message statuses.

Headers

• Authorization: Bearer YOUR_API_KEY

URL Parameters

Sample Requests

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

Response Format

Success Response

{
  "result": "success",
  "message": "Bulk operation found",
  "environment": "test",
  "bulk": {
    "id": "bulk_abc123def456",
    "name": "Monthly Newsletter - December 2024",
    "type": "email",
    "status": "completed",
    "totalRecipients": 1000,
    "successCount": 985,
    "failureCount": 15,
    "startTime": "2024-01-15T10:00:00Z",
    "endTime": "2024-01-15T10:15:00Z",
    "dateCreated": "2024-01-15T10:00:00Z",
    "details": {
      "provider": "postmark",
      "estimatedCompletion": null,
      "retryCount": 2
    }
  }
}

In Progress Response

{
  "result": "success",
  "message": "Bulk operation found",
  "environment": "test",
  "bulk": {
    "id": "bulk_xyz789abc123",
    "name": "SMS Campaign - January 2024",
    "type": "sms",
    "status": "processing",
    "totalRecipients": 5000,
    "successCount": 3200,
    "failureCount": 50,
    "startTime": "2024-01-15T14:00:00Z",
    "endTime": null,
    "dateCreated": "2024-01-15T14:00:00Z",
    "details": {
      "provider": "twilio",
      "estimatedCompletion": "2024-01-15T14:25:00Z",
      "retryCount": 0
    }
  }
}

Error Response

{
  "result": "error",
  "error": {
    "type": "NotFound",
    "message": "Bulk operation not found"
  }
}

Bulk Status Values

Bulk Types

• sms - SMS bulk notifications
• email - Email bulk notifications
• whatsapp - WhatsApp bulk notifications

Response Fields

Monitoring Bulk Operations

For large bulk operations, you can poll this endpoint periodically to monitor progress. We recommend checking status every 30-60 seconds for operations with thousands of recipients.

Polling Example

const pollBulkStatus = async (bulkId, intervalSeconds = 30) => {
  const poll = async () => {
    const response = await fetch(`https://api.ping.co.zw/v1/notification/api/bulk/${bulkId}`, {
      headers: { "Authorization": "Bearer sk_test_your_api_key_here" }
    });
    
    const result = await response.json();
    const bulk = result.bulk;
    
    console.log(`Status: ${bulk.status} - ${bulk.successCount}/${bulk.totalRecipients} completed`);
    
    if (bulk.status === 'completed' || bulk.status === 'failed' || bulk.status === 'cancelled') {
      console.log('Bulk operation finished:', bulk);
      return bulk;
    }
    
    // Continue polling
    setTimeout(poll, intervalSeconds * 1000);
  };
  
  poll();
};

pollBulkStatus("bulk_abc123def456");

Success Rate Calculation

Calculate the success rate of your bulk operations:

const calculateSuccessRate = (bulk) => {
  const processed = bulk.successCount + bulk.failureCount;
  const successRate = (bulk.successCount / processed) * 100;
  
  return {
    processed: processed,
    remaining: bulk.totalRecipients - processed,
    successRate: successRate.toFixed(2) + '%'
  };
};

Webhooks

For real-time updates, consider setting up webhooks to receive notifications when bulk operations complete. This is more efficient than polling for large operations.

Webhook Payload Example

{
  "event": "bulk.completed",
  "bulk_id": "bulk_abc123def456",
  "status": "completed",
  "total_recipients": 1000,
  "success_count": 985,
  "failure_count": 15,
  "timestamp": "2024-01-15T10:15:00Z"
}

Best Practices

• Store bulk IDs immediately after initiating bulk operations
• Implement reasonable polling intervals (30-60 seconds) to avoid rate limits
• Handle different status values appropriately in your application
• Monitor success rates and investigate high failure rates
• Set up alerts for failed bulk operations
• Use webhooks for real-time updates on large operations

Troubleshooting