Invio

Invia SMS in blocco con POST /v1/batches

POST/v1/batches

Invia a fino a 10.000 numeri in una richiesta. L'intero costo viene prelevato dal saldo in una volta sola.

Corpo della richiesta

  • toarray of stringsopzionale

    Numeri per un testo condiviso. Usa to con text, oppure messages.

  • textstringopzionale

    Il testo condiviso, richiesto con to.

  • messagesarray of objectsopzionale

    Uno {to, text} per destinatario, per testi personalizzati.

  • namestringopzionale

    Un'etichetta per la console, fino a 100 caratteri.

  • referencestringopzionale

    Il tuo id, fino a 100 caratteri, restituito sul batch e su ogni messaggio.

  • send_atstringopzionale

    Orario ISO 8601, da 2 minuti a 45 giorni in anticipo.

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": []
}

Numeri che sono stati esclusi

Ogni numero viene pulito e prezzato singolarmente. I numeri che non possono essere inviati vengono esclusi dal batch, non addebitati, e elencati in set_aside con una motivazione:

reasonSignificato
invalid_numberNon leggibile come + e da 7 a 15 cifre dopo la pulizia.
duplicateLo stesso numero è apparso precedentemente nella richiesta.
unsupported_countryIl numero non appartiene a un paese prezzato.
too_longIl suo testo personalizzato richiede più di 10 segmenti.
empty_textIl suo testo personalizzato è vuoto.
suppressedIl numero è nella tua lista di non invio.

Se non rimane alcun numero, la richiesta fallisce con il codice della prima motivazione (ad esempio invalid_number) e nulla viene addebitato.

Testo personalizzato per numero

Usa messages per dare a ogni destinatario il proprio testo: nomi, orari, importi. Ogni testo viene conteggiato e prezzato singolarmente, quindi un batch può mescolare messaggi di uno e due segmenti.

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." }
    ]
  }'

Pianificazione

Con send_at il batch e i suoi messaggi attendono nello stato scheduled e passano alla coda a quel minuto. Il costo viene prelevato quando la richiesta viene accettata, quindi un batch programmato ha sempre i suoi fondi. Un batch programmato può essere annullato fino a quando non inizia.

POST/v1/batches/{id}/cancel

Annulla un batch programmato: ogni messaggio viene annullato e l'intero costo torna al saldo come una riga di rimborso. Un batch che è iniziato risponde con 409 not_cancelable.

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

Recupera e elenca i batch

GET/v1/batches/{id}

Il batch con i conteggi in tempo reale per ogni stato. Interrogalo per monitorare l'avanzamento o utilizza i webhook.

GET/v1/batches

Batch dell'account, dal più recente, con limite (da 1 a 100) e starting_after (un ID bat_).

Campi del batch

  • idstring

    bat_ seguito da 12 caratteri.

  • statusstring

    programmato, in coda, in invio, completato o annullato.

  • sourcestring

    api o console.

  • encodingstring

    GSM-7, o UCS-2 quando il testo richiede Unicode.

  • recipientsinteger

    Numeri accettati nel batch.

  • max_segmentsinteger

    Conteggio segmenti più alto tra i testi.

  • coststring

    Totale prelevato dal saldo, USD.

  • refundedstring

    Totale restituito finora per messaggi falliti o annullati.

  • countsobject

    Messaggi per stato: programmato, in coda, inviato, consegnato, fallito, annullato.

  • send_atstring or null

    Orario programmato, se presente.

  • completed_atstring or null

    Quando l'ultimo messaggio ha raggiunto uno stato finale.

Liste più grandi

Dividi elenchi con oltre 10.000 numeri in più richieste, ciascuna con la propria Idempotency-Key (ad esempio l'ID dell'elenco e il numero della parte). I messaggi vengono passati alla rete in ordine fino a 1.200 al minuto per account, quindi una campagna con 50.000 numeri è in viaggio in meno di un'ora. La console accetta 50.000 numeri per campagna da un incolla o un file CSV.

Invia SMS in blocco con POST /v1/batches | Documentazione BulkSMSAPI