Skip to main content

​
Overview

Send SMS messages to all contacts within a specific contact group. This endpoint allows you to send messages to organized groups of contacts that you’ve created in your dashboard.

​
Endpoint

curl --request POST \
  "https://sms.lamah.com/api/sms/messages/contacts" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "message": "تذكير: معاينات عقارية متاحة هذا الأسبوع في الأندلس وقرقارش. للحجز رد بـ 1، للإلغاء رد بـ 0",
    "sender": "RealEstate",
    "payment_type": "wallet",
    "contact_group_id": "0198faa2-8ddd-72c7-afce-32d980bd60fe"
  }'

​
Request Parameters

ParameterTypeRequiredDescription
messagestring✅The SMS message content to send to all contacts
senderstring✅The sender ID (up to 11 characters)
payment_typestring✅Payment method: wallet or subscription
contact_group_idstring (UUID)✅ID of the contact group to send messages to

​
Parameter Details

The text content that will be sent to all contacts in the group.
  • 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 contacts in the group
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
The unique identifier of the contact group.
  • Format: UUID string (e.g., 123e4567-e89b-12d3-a456-426614174000)
  • Management: Contact groups are created and managed through your dashboard
  • Validation: Group must exist and belong to your project

​
Response

​
Success Response (200 OK)

{
  "message_id": "b9e8a1f2-4c60-4b0b-9f51-0c4f2f6c9e7a",
  "cost": 27,
  "details": { "sent": 27, "total": 30 }
}

​
Response Fields

FieldTypeDescription
message_idstringUUID of the created message batch
costnumberParts × total contacts in the group (as returned)
detailsobjectSummary of processing results

​
Summary Object Fields

FieldTypeDescription
sentintegerCount of recipients compatible with the sender provider
totalintegerTotal contacts in the group
The cost field is computed as parts × total contacts in the group. Actual wallet/subscription consumption is applied based on compatible recipients.

​
Error Responses

​
400 Bad Request - Invalid Group

{ "message": "Contact group not found" }

​
400 Bad Request - Incompatible Sender/Receivers

{ "message": "The sender and receivers are not compatible." }

​
401 Unauthorized

{ "message": "Unauthenticated." }

​
402 Payment Required

{ "message": "Insufficient balance" }

​
403 Forbidden

{ "message": "Forbidden" }

​
Contact Group Management

Contact groups are created and managed through your Lamah dashboard. You can view and manage your contact groups in the Contacts section.

​
Creating Contact Groups

  1. Log into Dashboard: Visit https://sms.lamah.com
  2. Navigate to Contacts: Go to the Contacts section
  3. Create New Group: Click “Create Contact Group”
  4. Add Contacts: Upload CSV file or add contacts manually
  5. Save Group: Give it a name and save

​
Viewing Contact Groups

You can retrieve your contact groups using the Get Project Contacts endpoint: 
curl --request GET \
  "https://sms.lamah.com/api/project/contacts/group_123e4567-e89b-12d3-a456-426614174000" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

​
Best Practices

Verify Group Size

Check group size before sending to estimate costs

Clean Contact Lists

Regularly clean your contact lists to remove invalid numbers

Segment Audiences

Create targeted groups for better engagement

Monitor Results

Track send results to improve future campaigns

​
Rate Limits

  • Contact Group Sends: 5 requests per minute
  • Contacts per minute: 10,000 total contacts across all group sends

​
Cost Estimation

Before sending to a large contact group, you can estimate costs: 
const estimateCost = async (contactGroupId) => {
  try {
    // First, get the contact group details
    const response = await fetch(`https://sms.lamah.com/api/project/contacts/${contactGroupId}`, {
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json'
      }
    });
    
    const groupData = await response.json();
    const contactCount = groupData.total_contacts;
    const estimatedCost = contactCount * 0.05; // Assuming $0.05 per SMS
    
    console.log(`Estimated cost for ${contactCount} contacts: $${estimatedCost}`);
    return estimatedCost;
    
  } catch (error) {
    console.error('Failed to estimate cost:', error);
    return null;
  }
};

​
Monitoring Send Progress

After initiating a contact group send, you can monitor the progress using the returned batch_id: 
const monitorSendProgress = async (batchId) => {
  // Implementation would depend on available batch status endpoint
  // This is a conceptual example
  console.log(`Monitoring batch: ${batchId}`);
};

​
Error Handling

const sendToContactGroup = async (messageData) => {
  try {
    const response = await fetch('https://sms.lamah.com/api/sms/messages/contacts', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(messageData)
    });

    if (!response.ok) {
      const error = await response.json();
      
      switch (error.code) {
        case 'GROUP_NOT_FOUND':
          console.error('Contact group not found:', error.details.contact_group_id);
          break;
        case 'EMPTY_GROUP':
          console.error('Contact group is empty:', error.details.group_name);
          break;
        case 'INSUFFICIENT_BALANCE':
          console.error(`Insufficient balance. Need $${error.details.estimated_cost}, have $${error.details.available_balance}`);
          break;
        default:
          console.error('Contact group send failed:', error.error);
      }
      return null;
    }

    const result = await response.json();
    console.log(`Sent to ${result.successful_sends}/${result.total_contacts} contacts`);
    return result;
    
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
};