🚀 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

Parameter	Type	Description	Example
`recipients`	array/string	Phone numbers list or comma/semicolon separated	`["+5511999888777", "+5521987654321"]`
`message`	string	SMS message content (up to 1600 characters)	`"Sua promoção especial!"`
`from`	string	Sender ID	`"MinhaLoja"`

Method 2: Individual Messages

Parameter	Type	Description	Example
`messages`	array	Array of individual message objects	See example below
`from`	string	Default sender ID (can be overridden per message)	`"MinhaMarca"`

Optional Parameters

Parameter	Type	Description	Default	Example
`batch_size`	integer	Messages per batch (max 10,000)	`1000`	`500`
`delay_between_batches`	integer	Delay in seconds between batches	`1`	`5`
`reference`	string	Your internal campaign ID	`null`	`"campaign_2025_01"`
`priority`	string	Message 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'];
}
?>