Envoi

Envoyer des SMS en masse avec POST /v1/batches

POST/v1/batches

Envoyez à jusqu'à 10 000 numéros en une seule requête. Le coût total est déduit du solde en une fois.

Corps de la requête

  • toarray of stringsoptionnel

    Numéros pour un texte partagé. Utilisez soit to avec text, soit messages.

  • textstringoptionnel

    Le texte partagé, requis avec to.

  • messagesarray of objectsoptionnel

    Un {to, text} par destinataire, pour des textes personnalisés.

  • namestringoptionnel

    Un libellé pour la console, jusqu'à 100 caractères.

  • referencestringoptionnel

    Votre propre id, jusqu'à 100 caractères, renvoyé sur le lot et chaque message.

  • send_atstringoptionnel

    Heure ISO 8601, de 2 minutes à 45 jours à l'avance.

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

Numéros mis de côté

Chaque numéro est nettoyé et tarifé individuellement. Les numéros qui ne peuvent pas être envoyés sont exclus du lot, non facturés, et listés dans set_aside avec une raison :

reasonSignification
invalid_numberNon lisible comme + et 7 à 15 chiffres après nettoyage.
duplicateLe même numéro est apparu plus tôt dans la requête.
unsupported_countryLe numéro n'appartient pas à un pays tarifé.
too_longSon texte personnalisé nécessite plus de 10 segments.
empty_textSon texte personnalisé est vide.
suppressedLe numéro est sur votre liste de non-envoi.

Si aucun numéro ne reste, la requête échoue avec le code de la première raison (par exemple invalid_number) et rien n'est facturé.

Texte personnalisé par numéro

Utilisez messages pour donner à chaque destinataire son propre texte : noms, heures, montants. Chaque texte est compté et tarifé individuellement, donc un lot peut mélanger des messages d'un et deux segments.

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

Planification

Avec send_at, le lot et ses messages attendent dans l'état scheduled et passent dans la file d'attente à cette minute. Le coût est prélevé lorsque la requête est acceptée, donc un lot planifié a toujours ses fonds. Un lot planifié peut être annulé jusqu'à son démarrage.

POST/v1/batches/{id}/cancel

Annule un lot planifié : chaque message devient annulé et le coût total retourne au solde sous forme d'une ligne de remboursement. Un lot qui a démarré répond avec 409 not_cancelable.

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

Récupérer et lister les lots

GET/v1/batches/{id}

Le lot avec les comptes en temps réel par statut. Interrogez-le pour suivre la progression, ou utilisez les webhooks.

GET/v1/batches

Les lots du compte, du plus récent au plus ancien, avec une limite (1 à 100) et starting_after (un identifiant bat_).

Champs du lot

  • idstring

    bat_ suivi de 12 caractères.

  • statusstring

    planifié, en file d'attente, en cours d'envoi, terminé ou annulé.

  • sourcestring

    api ou console.

  • encodingstring

    GSM-7, ou UCS-2 si un texte nécessite Unicode.

  • recipientsinteger

    Numéros acceptés dans le lot.

  • max_segmentsinteger

    Nombre maximal de segments parmi les textes.

  • coststring

    Total prélevé du solde, en USD.

  • refundedstring

    Total restitué jusqu'à présent pour les messages échoués ou annulés.

  • countsobject

    Messages par statut : planifiés, en file d'attente, envoyés, livrés, échoués, annulés.

  • send_atstring or null

    Heure planifiée, le cas échéant.

  • completed_atstring or null

    Lorsque le dernier message a atteint un statut final.

Listes plus longues

Divisez les listes de plus de 10 000 numéros en plusieurs requêtes, chacune avec sa propre Idempotency-Key (par exemple l'identifiant de la liste et le numéro de partie). Les messages sont transmis au réseau dans l'ordre à raison de 1 200 par minute et par compte, donc une campagne de 50 000 numéros est en route en moins d'une heure. La console prend 50 000 numéros par campagne à partir d'un collage ou d'un fichier CSV.

Envoyer des SMS en masse avec POST /v1/batches | Documentation BulkSMSAPI