BatchSMS API (1.0.0)

The Batch SMS API enables you to efficiently send SMS messages to multiple recipients with a single API call. This API offers advanced processing features, including batch scheduling, notification callbacks, and detailed status tracking.

• Bulk Processing: Send up to 1 million SMS messages with a single API call
• Scheduling: Schedule batches for future delivery
• Status Tracking: Monitor batch processing status in real-time
• Async Notifications: Receive batch progress notifications via webhooks
• Message Templating: Create personalized messages in a compact format

• https://api.spirius.com/batchsms

• 202 Accepted: Used for successful responses to POST /batches
• 200 OK: Used for all other successful responses
• 400: Malformed request or validation failure
• 401: Authentication failure
• 403: Forbidden
• 404: Not found
• 409: Conflict
• 413: Request payload too large
• 429: Rate limit errors

Authorization

Use Authorization with OAuth2 Bearer token. See Authentication section for details on how to obtain the token.

Authorization: Bearer <token>

Content-Type

Content-Type should be application/json.

Content-Type: application/json

Content-Encoding

All create batch requests must be compressed with gzip.

Content-Encoding: gzip

The sender_id controls how the sender appears on recipient devices. Supported types and rules:

• International

  • Must be in E.164 format (e.g., "+46701234567").

• Alphanumeric

  • Max length: 11 characters.
  • Allowed characters: letters (A–Z, a–z), numbers (0–9), Scandinavian characters (åäöÅÄÖ, æøÆØ), space (not at the beginning or end), dot (.), underscore (_), ampersand (&), and hyphen (-).
  • Note: Scandinavian characters typically only work for Scandinavian recipients.

• Shortcode

  • Digits only.
  • Length: 3–11 characters.

Request Size Limits

• Request size maximum: 32MB
• SMS length: Maximum 10 concatenated SMS (1600 characters for GSM-7, 700 for Unicode)

Request Size Examples

The sizes are estimates derived from test data, there will be variations in sizes depending on the actual content and how efficient the content can be compressed.

Static message, i.e. same message re-used for all recipients - Max length message (10 SMS)

Unique message for each recipient - Small message (1 SMS)

Unique message for each recipient - Max length message (10 SMS)

Note on request size: Requests larger than 32MB will be rejected. For large batches with unique messages, consider splitting into multiple smaller batches, or using message templates with personalization fields.

Note on SMS length: A single SMS can contain maximum 160 characters, or maximum 70 characters if it contains emojis or any other character that is not part of the GSM-7 character set. When sending longer messages, up to 10 SMS will be automatically concatenated to carry the message content. The maximum limit is imposed by mobile networks. When concatenating SMS, some overhead is used for the concatenation, so the actual number of characters in each SMS will be reduced to 153 characters for GSM-7 and 67 characters for Unicode. Individual messages that exceeds the 10 SMS limit will be rejected and marked as failed in the batch.

Recipients limit - API

• The API supports batches with up to 1 million recipients, provided that the request size does not exceed 32MB.

Recipients limit - SMS Account

• Each SMS account has a limit on the number of recipients for security and performance reasons. Contact your Spirius account manager to activate this API and customize the limit to your needs.

Rate Limits

• Batch requests: 1 r/s (for security reasons)
• Individual SMS: Up to 100 r/s (configured per account)

The batch SMS API will dynamically adjust the rate according to the capacity of the underlying SMS API and aims to get as close as possible to the max configured rate limit of the account.

• Batch statuses including message details are available up to 7 days after processing.
• This applies to both new requests and scheduled requests (7 days after the scheduled start time).

There are two ways to get batch status updates:

Polling

Use one of the following endpoints to get the status of the batch

Event Notifications

• Configure event callback in notification_settings of the create batch request. (See details below)

To receive asynchronous batch event notifications, set the following fields in the batch request:

• batch_event_callback_url: The URL to which the event notifications will be sent.
• batch_event_callback_token: An optional token to be included in the callback URL.

Callback with Token

If a token is provided in the request by the client, It is used by the server when doing the callbacks. A token can have a max length of 64 characters.

Token provided in batch request:

{
  ...
  "notification_settings": {
    "batch_event_callback_url": "https://client.com/batchsmsnotifications"
    "batch_event_callback_token": "0fb45e50-86bd-4935-a1e3-6c1ded88d58b",
  }
}

Token used in callback:

POST https://client.com/batchsmsnotifications?token=0fb45e50-86bd-4935-a1e3-6c1ded88d58b

batch.created

{
  "event_type": "batch.created",
  "timestamp": "2025-03-21T11:15:36Z",
  "batch_status_summary": {
    ... // Complete batch status summary information
  }
}

batch.scheduled

{
  "event_type": "batch.scheduled",
  "timestamp": "2025-03-21T11:15:36Z",
  "batch_status_summary": {
    ... // Complete batch status summary information
  }
}

batch.processing_started

{
  "event_type": "batch.processing_started",
  "timestamp": "2025-03-21T10:09:59Z",
  "batch_status_summary": {
    ... // Complete batch status summary information
  }
}

batch.submission_completed

{
  "event_type": "batch.submission_completed",
  "timestamp": "2025-03-21T10:09:59Z",
  "batch_status_summary": {
    ... // Complete batch status summary information
  }
}

batch.submission_progress_update

{
  "event_type": "batch.submission_progress_update",
  "timestamp": "2025-03-21T10:09:59Z",
  "submission_progress_percentage": 95,
  "batch_status_summary": {
    ... // Complete batch status summary information
  },
  "submitted_messages_delta": [
    {
      "id": "c58b5ebb-076d-4058-b3d9-a3a01f230bb2",
      "external_message_id": "1",
      "transaction_id": "02df77cc-b1ce-46b6-89bd-3183a969f855",
      "phone_number": "+34693363516",
      "message": "Hello World!",
      "submission_status": "SUBMITTED",
      "submission_time": "2025-03-21T08:29:00Z",
    },
    {
      "id": "166269f1-6147-4154-afe3-49c8ad616235",
      "external_message_id": "2",
      "transaction_id": "e9f63cfd-1e20-4784-b3a7-d131384f4d32",
      "phone_number": "+34604224206",
      "message": "Hello World!",
      "submission_status": "SUBMITTED",
      "submission_time": "2025-03-21T08:30:00Z",
    }
  ]
}

batch.canceled

{
  "event_type": "batch.canceled",
  "timestamp": "2025-03-21T14:47:57Z",
  "batch_status_summary": {
    ... // Complete batch status summary information
  }
}

batch.failed

{
  "event_type": "batch.failed",
  "timestamp": "2025-03-21T14:47:57Z",
  "batch_status_summary": {
    ... // Complete batch status summary information
  }
}

Endpoints for obtaining OAuth2 authentication tokens.

Endpoints for creating and managing SMS batches.

API health check endpoints.