Skip to main content
API docs by Redocly

BatchSMS API (1.0.0)

Download OpenAPI specification:Download

Spirius Support: support@spirius.com URL: https://www.spirius.com/contact

BatchSMS API Description

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.

Key Features

  • 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

HTTP Response Codes used

  • 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

HTTP Headers

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

Sender ID formats

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.

Limitations

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)

Number of GSM-7 characters Number of recipients/messages Size - Uncompressed Size - Compressed
1530 (max size) 10,000 0.9 MB 0.1 MB
1530 100,000 9.1 MB 0.9 MB
1530 1,000,000 91 MB 8.4 MB

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

Number of GSM-7 characters Number of recipients/messages Size - Uncompressed Size - Compressed
160 10,000 2.6 MB 1.3 MB
160 100,000 27 MB 13 MB
160 1,000,000 266 MB 131 MB

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

Number of GSM-7 characters Number of recipients/messages Size - Uncompressed Size - Compressed
1530 (max size) 10,000 16 MB 11 MB
1530 100,000 157 MB 114 MB
1530 1,000,000 1500 MB 1100 MB

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.

Data Retention

  • 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).

Getting Batch Status updates

There are two ways to get batch status updates:

Polling

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

Endpoint Description
/v1/batches/{batch_id}/poll Poll batch status, summary only
/v1/batches/{batch_id}/poll_with_delta Poll batch status, summary + message delta information

Event Notifications

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

Batch Event Notifications

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

Event Types

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
  }
}

Authentication

Endpoints for obtaining OAuth2 authentication tokens.

OAuth2 Access Token

OAuth2 token endpoint implementing the client credentials flow.

This endpoint validates client credentials (SMS API account and key) and issues a JWT token if the credentials are valid.

The client_id is the SMS API account, and the client_secret is the SMS API key.

Args: json_data: OAuth2 JSON payload containing client_id and client_secret auth_service: AuthService for credential validation and token creation

Returns: Token object containing the JWT access token and metadata

Raises: HTTPException: If client authentication fails

Request Body schema: application/json
required
client_id
required
string (Client Id)

SMS API account name

client_secret
required
string (Client Secret)

SMS API key

grant_type
string (Grant Type)
Default: "client_credentials"

OAuth2 grant type

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials",
  • "client_id": "string",
  • "client_secret": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "expires_in": 0
}

Batches

Endpoints for creating and managing SMS batches.

Create a batch

Create a new batch of SMS messages.

This endpoint allows you to create a batch of SMS messages to be sent to multiple recipients. The batch will be processed asynchronously, and you'll receive a batch ID to track its status.

Detailed field descriptions are available in the API schema documentation.

Key capabilities:

  • Personalized messaging via templates, optionally using double curly brackets {{field_name}} placeholders combined with 'field_message' for value substitution in recipients
  • Support for up to 1,000,000 recipients per batch
  • Scheduled delivery with the schedule_at parameter
  • Batch status callbacks and delivery receipt tracking
  • Dry run mode for testing without sending actual messages

Compression Requirement

This endpoint requires the request to be compressed with gzip due to potential large payload sizes. Set the 'Content-Encoding: gzip' header and compress the request body.

One Active Batch Per Account

An account can run one batch at a time. While a batch of yours is being assembled, processing, pausing or paused, another immediate batch on the same account returns 409 Conflict with the id of the batch that is holding it. A scheduled batch is accepted regardless, and starts once the account is free.

Authorizations:
OAuth2PasswordBearer
header Parameters
content-encoding
required
string (Content-Encoding)

Must be set to 'gzip' for compressed requests

Request Body schema: application/json
required
required
object (Batch)

Batch configuration

required
object (BatchSmsConfig-Input)

SMS configuration

required
Array of objects (Recipients)

List of recipients to send messages to

External Batch Id (string) or External Batch Id (null) (External Batch Id)

External batch identifier

Schedule At (string) or Schedule At (null) (Schedule At)

Scheduled delivery time in ISO 8601 format (e.g., '2023-01-01T12:00:00'). Max 7 days in the future.

BatchNotificationSettings (object) or null

Notification settings

Responses

Request samples

Content type
application/json
{
  • "batch": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Get batch information

Get comprehensive status and configuration of a batch by its ID.

This endpoint returns complete batch information including:

  • Batch status summary (status, timestamps, message counts)
  • SMS configuration (sender ID, message template, etc.)
  • Notification settings

Don't use this endpoint for polling status.

Authorizations:
OAuth2PasswordBearer
path Parameters
batch_id
required
string (Batch Id)

Responses

Response samples

Content type
application/json
{
  • "batch_status_summary": {
    },
  • "sms_config": {
    },
  • "notification_settings": {
    }
}

Poll batch status summary

Get batch status summary.

This endpoint efficiently supports polling for status changes by only returning:

  • Current batch status summary

It's designed for clients to repeatedly call to monitor batch progress.

Authorizations:
OAuth2PasswordBearer
path Parameters
batch_id
required
string (Batch Id)

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2019-08-24T14:15:22Z",
  • "batch_status_summary": {
    }
}

Poll batch status summary with messages delta

Get batch status and message changes since a specific sequence point.

This endpoint efficiently supports polling for status changes by only returning:

  • Current batch status summary
  • Messages that changed status since the last_sequence_id
  • Information about whether more changes are available

It's designed for clients to repeatedly call to monitor batch progress.

Authorizations:
OAuth2PasswordBearer
path Parameters
batch_id
required
string (Batch Id)
query Parameters
last_sequence_id
integer (Last Sequence Id) >= 0
Default: 0
max_delta_size
integer (Max Delta Size) [ 1 .. 2000 ]
Default: 500

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2019-08-24T14:15:22Z",
  • "batch_status_summary": {
    },
  • "next_sequence": 0,
  • "has_more": true,
  • "submitted_messages_delta": [
    ]
}

Cancel a batch

Cancel a batch.

A batch can be canceled while it is scheduled, processing, pausing or paused. The batch is canceled immediately and the response reports it as CANCELED.

Note that submissions already in flight when the cancel arrives may still reach the SMS network; those messages are counted truthfully in the batch's final statistics, so the submitted count can keep rising briefly after the cancel returns.

A batch that has already completed or been canceled returns 409 Conflict.

Authorizations:
OAuth2PasswordBearer
path Parameters
batch_id
required
string (Batch Id)

Responses

Response samples

Content type
application/json
{
  • "batch_status_summary": {
    }
}

Pause a batch

Pause a batch that is processing or scheduled.

Pausing a processing batch happens in two phases. The response is immediate and reports the batch as PAUSING: submission stops within about ten seconds, and once the batch has stopped sending and every confirmed result is recorded, it settles in PAUSED. Poll the batch, or subscribe to the batch.paused event, to learn when it has settled. Messages already handed to the SMS network before the pause took effect are sent normally.

A batch with nothing left to stop - a scheduled one that has not started, or one that has already come to a halt - reports PAUSED right away. A paused scheduled batch will not start at its scheduled time until it is resumed.

Pausing a batch that is already pausing or paused changes nothing and succeeds. A batch that has completed, failed or been canceled returns 409 Conflict.

Pause and resume may not be issued in rapid succession on the same batch; a request inside the minimum interval returns 409 Conflict.

Authorizations:
OAuth2PasswordBearer
path Parameters
batch_id
required
string (Batch Id)

Responses

Response samples

Content type
application/json
{
  • "batch_status_summary": {
    }
}

Resume a paused batch

Resume a paused batch.

Submission continues with exactly the messages that were not dispatched before the pause; no message is ever sent twice. A batch that was paused before its scheduled time returns to SCHEDULED and starts at that time; every other paused batch reports PROCESSING and continues immediately.

The account is re-checked before the batch leaves PAUSED, so an account that became inactive while the batch was paused returns 403 Forbidden and the batch stays paused.

Only a PAUSED batch can be resumed; any other state returns 409 Conflict, as does a resume issued inside the minimum pause/resume interval.

Authorizations:
OAuth2PasswordBearer
path Parameters
batch_id
required
string (Batch Id)

Responses

Response samples

Content type
application/json
{
  • "batch_status_summary": {
    }
}

Health

API health check endpoints.

API Health Check

Simple health check endpoint that verifies the API is operational.

Returns a JSON response with "status": "OK" when the API is functioning correctly. This endpoint can be used by monitoring systems to verify API availability.

Returns: HealthResponse: Status information indicating the API is healthy

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}