Skip to main content

​
Overview

Send the same SMS message to multiple recipients in a single API call. This is more efficient than sending individual messages when you need to reach multiple people with the same content.

​
Endpoint

curl --request POST \
  "https://sms.lamah.com/api/sms/messages/bulk" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "message": "عروض عقارية مميزة في طرابلس وبنغازي — شقق جاهزة للسكن وتقسيط ميسر.",
    "sender": "RealEstate",
    "payment_type": "wallet",
    "receivers": [
      "00218912345678",
      "00218922654321",
      "00218944678901"
    ]
  }'

​
Request Parameters

ParameterTypeRequiredDescription
messagestring✅The SMS message content to send to all recipients
senderstring✅The sender ID (up to 11 characters)
payment_typestring✅Payment method: wallet or subscription
receiversarray✅Array of phone numbers in international format

​
Parameter Details

The text content that will be sent to all recipients.
  • Maximum length: 160 characters for single SMS, 1530 characters for concatenated SMS
  • Encoding: UTF-8 supported for international characters
  • Consistency: Same message is sent to all recipients
The sender ID that will appear on all recipients’ devices.
  • Length: Maximum 11 characters
  • Format: Alphanumeric characters only
  • Examples: Lamah, MyCompany, Alert123
Specifies how the SMS costs will be charged.
  • wallet: Deduct from your account balance
  • subscription: Use your subscription plan credits
Array of recipient phone numbers.
  • Format: Each number must include country code (e.g., 00218912345678)
  • Limit: Maximum 1000 recipients per request
  • Validation: All numbers are validated before sending
  • Duplicates: Duplicate numbers are automatically removed

​
Response

​
Success Response (200 OK)

{
  "message_id": "batch_123456789",
  "cost": 3,
  "details": {
    "sent": 3,
    "total": 3
  }
}

​
Response Fields

FieldTypeDescription
message_idstringUnique identifier for the bulk send batch
costnumberTotal cost for all messages
detailsobjectSummary of recipients processed: sent and total

​
Message Object Fields

FieldTypeDescription
message_idstringUnique identifier for the individual message
costnumberCost for this specific message

​
401 Unauthorized

{
    "message": "Unauthenticated."
}

​
Limits and Considerations

Recipient Limit: Maximum 1000 recipients per bulk send request. For larger lists, split into multiple requests.
Cost Efficiency: Bulk sending is more cost-effective than individual sends for the same message to multiple recipients.

​
Rate Limits

  • Bulk SMS Endpoint: 10 requests per minute
  • Recipients per minute: 10,000 total recipients across all bulk requests

​
Best Practices

  1. Validate phone numbers before adding to the receivers array
  2. Remove duplicates to avoid unnecessary charges
  3. Split large lists into batches of 1000 or fewer
  4. Monitor batch status using the returned batch_id
  5. Handle partial failures gracefully in your application

​
Batch Processing Example

const sendBulkSMS = async (message, sender, allReceivers) => {
  const batchSize = 1000;
  const batches = [];
  
  // Split receivers into batches
  for (let i = 0; i < allReceivers.length; i += batchSize) {
    const batch = allReceivers.slice(i, i + batchSize);
    batches.push(batch);
  }
  
  const results = [];
  
  // Send each batch
  for (const receivers of batches) {
    try {
      const response = await fetch('https://sms.lamah.com/api/sms/messages/bulk', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          message,
          sender,
          payment_type: 'wallet',
          receivers
        })
      });
      
      const result = await response.json();
      results.push(result);
      
      // Wait between batches to respect rate limits
      await new Promise(resolve => setTimeout(resolve, 6000));
      
    } catch (error) {
      console.error('Batch send failed:', error);
    }
  }
  
  return results;
};