Envio

Envie SMS em massa com POST /v1/batches

POST/v1/batches

Envie para até 10.000 números em uma solicitação. O custo total é deduzido do saldo de uma vez.

Corpo da solicitação

  • toarray of stringsopcional

    Números para um texto compartilhado. Use to com text ou messages.

  • textstringopcional

    O texto compartilhado, obrigatório com to.

  • messagesarray of objectsopcional

    Um {to, text} por destinatário, para textos personalizados.

  • namestringopcional

    Um rótulo para o console, até 100 caracteres.

  • referencestringopcional

    Seu próprio id, até 100 caracteres, retornado no lote e em cada mensagem.

  • send_atstringopcional

    Horário ISO 8601, de 2 minutos a 45 dias à frente.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-sale-0412" \
  -d '{
    "name": "Spring sale",
    "text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
    "to": [
      "+14155550123",
      "+447400123456",
      "+4915123456789"
    ]
  }'
202 AcceptedJSON
{
  "id": "bat_6TQ2W8M1ZK4N",
  "object": "batch",
  "name": "Spring sale",
  "status": "queued",
  "source": "api",
  "encoding": "GSM-7",
  "recipients": 3,
  "max_segments": 1,
  "cost": "0.02741",
  "refunded": "0.00000",
  "currency": "USD",
  "counts": { "scheduled": 0, "queued": 3, "sent": 0, "delivered": 0, "failed": 0, "canceled": 0 },
  "send_at": null,
  "reference": null,
  "created_at": "2026-11-07T09:31:40.102Z",
  "completed_at": null,
  "set_aside": []
}

Números que são reservados

Cada número é limpo e precificado individualmente. Números que não podem ser enviados são excluídos do lote, não cobrados, e listados em set_aside com um motivo:

reasonSignificado
invalid_numberNão legível como + e 7 a 15 dígitos após a limpeza.
duplicateO mesmo número apareceu anteriormente na solicitação.
unsupported_countryO número não pertence a um país com preço definido.
too_longSeu texto personalizado precisa de mais de 10 segmentos.
empty_textSeu texto personalizado está vazio.
suppressedO número está na sua lista de não enviar.

Se nenhum número restar, a solicitação falha com o código do primeiro motivo (por exemplo, invalid_number) e nada é cobrado.

Texto personalizado por número

Use messages para dar a cada destinatário seu próprio texto: nomes, horários, valores. Cada texto é contado e precificado individualmente, então um lote pode misturar mensagens de um e dois segmentos.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminders, 14 May",
    "send_at": "2026-05-13T16:00:00Z",
    "messages": [
      { "to": "+14155550123", "text": "Hi Ana, your dental check-up is tomorrow at 09:30." },
      { "to": "+14155550178", "text": "Hi Sam, your dental check-up is tomorrow at 11:00." }
    ]
  }'

Agendamento

Com send_at, o lote e suas mensagens aguardam no status scheduled e entram na fila naquele minuto. O custo é deduzido quando a solicitação é aceita, então um lote agendado sempre tem seus fundos. Um lote agendado pode ser cancelado até que comece.

POST/v1/batches/{id}/cancel

Cancela um lote agendado: cada mensagem é cancelada e o custo total retorna ao saldo como uma linha de reembolso. Um lote que começou responde com 409 not_cancelable.

curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

Recupere e liste lotes

GET/v1/batches/{id}

O lote com contagens em tempo real por status. Consulte-o para acompanhar o progresso ou use webhooks.

GET/v1/batches

Lotes da conta, do mais recente para o mais antigo, com limite (1 a 100) e starting_after (um ID bat_).

Campos do lote

  • idstring

    bat_ seguido por 12 caracteres.

  • statusstring

    agendado, na fila, enviando, concluído ou cancelado.

  • sourcestring

    api ou console.

  • encodingstring

    GSM-7 ou UCS-2 quando algum texto precisar de Unicode.

  • recipientsinteger

    Números aceitos no lote.

  • max_segmentsinteger

    Maior contagem de segmentos entre os textos.

  • coststring

    Total debitado do saldo, em USD.

  • refundedstring

    Total devolvido até agora para mensagens falhas ou canceladas.

  • countsobject

    Mensagens por status: agendadas, na fila, enviadas, entregues, falhas, canceladas.

  • send_atstring or null

    Horário agendado, se houver.

  • completed_atstring or null

    Quando a última mensagem atingiu um status final.

Listas maiores

Divida listas com mais de 10.000 números em várias requisições, cada uma com sua própria Idempotency-Key (por exemplo, o ID da lista e o número da parte). As mensagens são entregues à rede em ordem, a até 1.200 por minuto por conta, então uma campanha com 50.000 números estará a caminho em menos de uma hora. O console aceita 50.000 números por campanha a partir de um texto colado ou arquivo CSV.

Envie SMS em massa com POST /v1/batches | Documentação BulkSMSAPI