Bulk SMS

Send SMS messages to multiple recipients in a single API call.

Overview

The Bulk SMS API allows you to send SMS messages to multiple recipients efficiently. Each recipient can have a custom message, or you can send the same message to all recipients.

Authentication

All bulk SMS requests require authentication using your API key via the X-API-Key header.

X-API-Key: your_api_key_here

Base URL

Production: https://sms.chinqit.com/api/v2

Send Bulk Messages

POST /bulk/send

Send SMS messages to multiple recipients in a single request.

Request Body

Parameter	Type	Required	Description
recipients	array	Yes	Array of recipient objects (max 50,000)
recipients[].phone	string	Yes	Phone number in international format
recipients[].message	string	Yes	Message text for this recipient

Example Request

{
  "recipients": [
    {
      "phone": "+22238089336",
      "message": "Hello John, your order is ready!"
    },
    {
      "phone": "+22238089337",
      "message": "Hello Sarah, your order is ready!"
    }
  ]
}

Success Response (202 Accepted)

{
  "success": true,
  "message": "Bulk batch created successfully",
  "batchId": "550e8400-e29b-41d4-a716-446655440000",
  "totalValid": 2,
  "totalInvalid": 0,
  "estimatedCost": 0.04,
  "status": "processing"
}

Error Responses

400 Bad Request - Validation Error

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "path": ["recipients"],
      "message": "Array must contain at least 1 element(s)"
    }
  ]
}

402 Payment Required - Insufficient Balance

{
  "success": false,
  "message": "Insufficient balance",
  "details": {
    "requiredAmount": 0.04,
    "validRecipients": 2,
    "invalidRecipients": 0
  }
}

400 Bad Request - No Valid Recipients

{
  "success": false,
  "message": "No valid recipients found",
  "invalidRecipients": [
    {
      "phone": "invalid",
      "reason": "Invalid phone number format"
    }
  ]
}

Get Batch Status

GET /bulk/status/:batchId

Retrieve the status of a bulk send batch.

URL Parameters

Parameter	Type	Required	Description
batchId	string	Yes	The batch ID returned from the send request

Example Response

{
  "success": true,
  "batch": {
    "batchId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "totalMessages": 100,
    "validMessages": 98,
    "invalidCount": 2,
    "successfulCount": 45,
    "failedCount": 5,
    "totalCost": 1.96,
    "progress": 51,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:31:30.000Z",
    "messages": [
      {
        "messageId": "msg-123",
        "phone": "+22238089336",
        "status": "sent"
      },
      {
        "messageId": "msg-124",
        "phone": "+22238089337",
        "status": "failed",
        "error": "Invalid destination address"
      }
    ]
  }
}

Status Values

Status	Description
pending	Batch created, awaiting processing
processing	Messages are being queued and sent
completed	All messages sent successfully
partial	Some messages succeeded, some failed
failed	All messages failed

Message Status Values

Status	Description
pending	Message awaiting processing
queued	Message queued for sending
sent	Message sent successfully
failed	Message failed to send

Rate Limits

• Maximum 50,000 recipients per batch
• Maximum 100 batches per hour per API key
• Messages are queued and sent at the system's configured rate

Phone Number Format

Accepted formats for Mauritania numbers:

• +22238089336 (International format with +)
• 22238089336 (International format without +)
• 38089336 (Local format, 8 digits starting with 2, 3, or 4)

Billing

• Cost is calculated per message based on message length and encoding
• Funds are deducted upfront when the batch is created
• Failed messages are automatically refunded
• Long messages (multi-part) are charged per SMS part

Code Examples

JavaScript/Node.js

const response = await fetch('https://sms.chinqit.com/api/v2/bulk/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    recipients: [
      { phone: '+22238089336', message: 'Hello!' },
      { phone: '+22238089337', message: 'Hi there!' }
    ]
  })
});

const result = await response.json();
console.log(result.batchId);

Python

import requests

response = requests.post(
    'https://sms.chinqit.com/api/v2/bulk/send',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key_here'
    },
    json={
        'recipients': [
            {'phone': '+22238089336', 'message': 'Hello!'},
            {'phone': '+22238089337', 'message': 'Hi there!'}
        ]
    }
)

result = response.json()
print(result['batchId'])

PHP

<?php
$ch = curl_init('https://sms.chinqit.com/api/v2/bulk/send');

$data = [
    'recipients' => [
        ['phone' => '+22238089336', 'message' => 'Hello!'],
        ['phone' => '+22238089337', 'message' => 'Hi there!']
    ]
];

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key_here'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo $result['batchId'];

cURL

curl -X POST https://sms.chinqit.com/api/v2/bulk/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "recipients": [
      {"phone": "+22238089336", "message": "Hello!"},
      {"phone": "+22238089337", "message": "Hi there!"}
    ]
  }'

Polling for Status

After sending a batch, poll the status endpoint every 2-5 seconds until the batch completes:

const checkStatus = async (batchId) => {
  const response = await fetch(`https://sms.chinqit.com/api/v2/bulk/status/${batchId}`, {
    headers: { 'X-API-Key': 'your_api_key_here' }
  });
  
  const result = await response.json();
  
  if (['completed', 'failed', 'partial'].includes(result.batch.status)) {
    console.log('Batch complete!', result.batch);
    return result.batch;
  }
  
  // Continue polling
  console.log(`Progress: ${result.batch.progress}%`);
  setTimeout(() => checkStatus(batchId), 2000);
};

Error Codes

Code	Description
NO_CREDIT	Insufficient balance
BILLING_FAILED	Billing transaction failed
INVALID_DESTINATION	Invalid phone number format
QUEUE_ERROR	Failed to queue message

Best Practices

1. Validate phone numbers before sending to avoid unnecessary costs
2. Poll for status to track message delivery
3. Handle partial failures - some messages may succeed while others fail
4. Batch size - Keep batches under 10,000 for optimal performance
5. Retry logic - Failed messages are automatically retried up to 4 times