API Reference

Send bulk SMS Messages

Send SMS messages to large groups of recipients efficiently with our bulk SMS API. Perfect for marketing campaigns, notifications, and mass communications with optimized delivery and cost management. ##

🚀 Quick Start

Basic Bulk SMS

curl -X POST "https://api.airtexts.com/sms/send-bulk" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      "+5511999888777",
      "+5521987654321", 
      "+5531876543210"
    ],
    "from": "YourBrand",
    "message": "Promoção especial! 50% OFF em todos os produtos. Válido até amanhã!"
  }'

Bulk SMS with Personalization

curl -X POST "https://api.airtexts.com/sms/send-bulk" \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "to": "+5511999888777",
        "message": "Olá João, sua conta vence em 3 dias. Renove já!"
      },
      {
        "to": "+5521987654321", 
        "message": "Olá Maria, sua conta vence em 3 dias. Renove já!"
      },
      {
        "to": "+5531876543210",
        "message": "Olá Pedro, sua conta vence em 3 dias. Renove já!"
      }
    ],
    "from": "MinhaEmpresa"
  }'

Bulk SMS with CSV Import

curl -X POST "https://api.airtexts.com/sms/send-bulk" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": "+5511999888777,+5521987654321;+5531876543210,+5541765432109",
    "from": "Loja123",
    "message": "Chegaram novos produtos na nossa loja! Confira: www.loja123.com.br",
    "batch_size": 1000
  }'

📋 Request Parameters

Method 1: Same Message to Multiple Recipients

ParameterTypeDescriptionExample
recipientsarray/stringPhone numbers list or comma/semicolon separated["+5511999888777", "+5521987654321"]
messagestringSMS message content (up to 1600 characters)"Sua promoção especial!"
fromstringSender ID"MinhaLoja"

Method 2: Individual Messages

ParameterTypeDescriptionExample
messagesarrayArray of individual message objectsSee example below
fromstringDefault sender ID (can be overridden per message)"MinhaMarca"

Optional Parameters

ParameterTypeDescriptionDefaultExample
batch_sizeintegerMessages per batch (max 10,000)1000500
delay_between_batchesintegerDelay in seconds between batches15
referencestringYour internal campaign IDnull"campaign_2025_01"
prioritystringMessage priority (normal, high)"normal""high"

Comma/Semicolon Separated Format

{
  "recipients": "+5511999888777,+5521987654321;+5531876543210,+5541765432109",
  "from": "MinhaMarca", 
  "message": "Suporte para separadores mistos!"
}

Personalized Messages Format

{
  "messages": [
    {
      "to": "+5511999888777",
      "message": "Olá João! Seu pedido #1234 foi enviado.",
      "reference": "pedido_1234"
    },
    {
      "to": "+5521987654321",
      "message": "Oi Maria! Sua consulta é amanhã às 14h.",
      "reference": "consulta_maria"
    }
  ],
  "from": "ClinicaSaude"
}

✅ Success Response

Bulk SMS Response

{
  "status": "success",
  "message": "Bulk SMS sent successfully",
  "data": {
    "campaign_id": "bulk_67890abcdef12345",
    "total_recipients": 1500,
    "successful": 1485,
    "failed": 15,
    "total_cost": 74.25,
    "balance": 925.75,
    "batches": 2,
    "estimated_delivery_time": "5-10 minutes",
    "summary": {
      "queued": 1485,
      "processing": 0,
      "sent": 0,
      "delivered": 0,
      "failed": 15
    }
  }
}

Detailed Batch Response

{
  "status": "success",
  "message": "Bulk SMS queued successfully",
  "data": {
    "campaign_id": "bulk_67890abcdef12345",
    "batches": [
      {
        "batch_id": "batch_001",
        "recipients": 1000,
        "status": "queued",
        "scheduled_time": "2025-08-20T15:00:00Z"
      },
      {
        "batch_id": "batch_002", 
        "recipients": 500,
        "status": "queued",
        "scheduled_time": "2025-08-20T15:01:00Z"
      }
    ],
    "failed_numbers": [
      {
        "number": "+55119998887",
        "error": "Invalid phone number format"
      }
    ]
  }
}

❌ Error Responses

Insufficient Balance

{
  "error": "Insufficient balance for bulk SMS",
  "balance": 25.50,
  "required": 150.75,
  "recipients": 3015
}

🎯 Implementation Examples

PHP Bulk SMS

<?php
function sendBulkSMS($recipients, $message, $from = 'MinhaMarca') {
    $data = [
        'recipients' => is_array($recipients) ? $recipients : explode(',', $recipients),
        'from' => $from,
        'message' => $message,
        'batch_size' => 1000
    ];

    $ch = curl_init('https://api.airtexts.com/sms/send-bulk');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-Key: your_api_key',
        'X-API-Secret: your_api_secret',
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $result = json_decode($response, true);
    curl_close($ch);

    return $result;
}

// Bulk SMS para lista de clientes brasileiros
$clientes = [
    '+5511999888777',
    '+5521987654321',
    '+5531876543210',
    '+5541765432109',
    '+5551654321098'
];

$mensagem = 'Promoção especial! 30% OFF em toda loja. Corra!';
$resultado = sendBulkSMS($clientes, $mensagem, 'MinhaLoja');

if ($resultado['status'] === 'success') {
    echo "Bulk SMS enviado com sucesso!";
    echo "Campanha ID: " . $resultado['data']['campaign_id'];
    echo "Total enviados: " . $resultado['data']['successful'];
    echo "Custo total: R$ " . number_format($resultado['data']['total_cost'], 2);
} else {
    echo "Erro: " . $resultado['error'];
}
?>
Language
Credentials
Bearer
Click Try It! to start a request and see the response here!