Skip to main content

BatchSMS API (1.0.0)

Download OpenAPI specification:Download

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
  • 500: Unexpected server error
  • 503: The credentials could not be checked right now; retry after Retry-After seconds

Error Responses

Every error response has the same body, served with Content-Type: application/json.

Member Always present Description
code Yes Specific error code, e.g. MESSAGE_TOO_LONG. Stable; branch on this.
message Yes Human-readable explanation of this error, e.g. naming the batch and its state. Do not parse it.
details No Data belonging to the error code (see below).
error_code Yes Deprecated. Same value as code, except API_ERROR on the refusals that answered with it before: 401 (UNAUTHORIZED), 404 (NOT_FOUND), 405 (METHOD_NOT_ALLOWED) and the gzip checks (VALIDATION_ERROR).
error_message Yes Deprecated. The text earlier versions answered with. Use message.

details members:

Member Error code Description
errors Request validation errors One entry per failing input: field (path, e.g. batch.sms_config.sender_id or batch.recipients[3].message; a header or query parameter by its name), description (what is wrong) and reason (short machine-readable reason, e.g. missing). error and type are deprecated copies of description and reason.
extension Some codes Data specific to this API. extension.active_batch_id (ACCOUNT_BATCH_ALREADY_ACTIVE): the batch that is still active.

On a 500 the message is always the same opaque text; contact support with the request path and time. On a 503 (SERVICE_UNAVAILABLE) the message is always A temporary error occurred. Retry shortly.; retry after the Retry-After header's seconds, the credentials were not refused.

Example:

{
  "code": "MISSING_REQUIRED_FIELD",
  "message": "Validation error in request data",
  "details": {
    "errors": [
      { "field": "batch.sms_config.sender_id", "description": "Field required", "reason": "missing",
        "error": "Field required", "type": "missing" }
    ]
  },
  "error_code": "MISSING_REQUIRED_FIELD",
  "error_message": "Validation error in request data"
}

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 (about 1530 characters for GSM-7, 670 for UCS-2). See Message Length.
  • message_template: Maximum 1600 characters

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.

Message Length

A message longer than one SMS is sent as up to 10 concatenated SMS parts. A message that needs more than 10 parts is not sent (see Validation).

The encoding is chosen per message:

  • GSM-7: used when every character is in the GSM 03.38 basic or extension table. The basic table covers A-Z, a-z, 0-9, space, line feed, common punctuation and some accented letters (e.g. ÄÖÜÑ äöüñ ÅåÆæØø éèùìòàÇ).
  • UCS-2: used when any character is outside those tables, e.g. emoji, most accented letters not listed above, and non-Latin scripts.
Encoding Unit Single SMS Per part when concatenated 10 parts
GSM-7 septet 160 153 about 1530 characters
UCS-2 octet (2 per character) 140 (70 characters) 134 (67 characters) about 670 characters

Counting rules:

  • GSM-7 extension characters cost 2 septets each: ^ { } \ [ ] ~ | € and form feed. An extension character is never split across two parts, so a part can end up holding 152 septets.
  • In UCS-2, an emoji and other characters outside the Basic Multilingual Plane cost 4 octets (2 characters' worth).
  • A CRLF line break counts as one line feed.
  • One UCS-2 character anywhere in the message switches the whole message to UCS-2.

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

Validation

A batch is checked twice: when it is created, and per message when processing starts.

Refused at create time

These checks refuse the whole request with 400 and the code of the failed check. No batch is created.

code Refused when
MESSAGE_TOO_LONG The message_template text, with every {{field}} placeholder removed, needs more than 10 SMS parts, and at least one recipient has no own message (so relies on the template). message states the part count, and says the fields were not counted when the template has any.
INVALID_MESSAGE_TEMPLATE message_template is longer than 1600 characters
RECIPIENT_INVALID The batch has no message_template and one or more recipients have no message. message gives how many, and the position and phone number of the first.
INVALID_CLIENT_REFERENCE sms_config.client_reference is longer than 64 characters
INVALID_CALLBACK_URL batch_event_callback_url or sms_dlr_callback_url is set and is not an absolute http or https URL
INVALID_CALLBACK_TOKEN batch_event_callback_token is longer than 64 characters or contains anything other than letters, digits, - and _

Failed at processing

When processing starts, each message is built (template filled in, or the recipient's own message) and checked before it is sent. A message that fails a check:

  • is stored with submission_status FAILED, failed_at and the reason in error_message
  • is never sent
  • appears in submitted_messages_delta of poll_with_delta and of batch.submission_progress_update events
  • is counted in messages_submission_status.failed and in failure_reasons

The rest of the batch is sent as usual. A batch where every message fails still ends in status SUBMISSION_COMPLETED.

Checks run in this order; the first failing check gives the reason:

error_message Failed when
Phone number is not valid phone_number is shorter than 5 characters, or contains anything other than digits, +, - and spaces
external_message_id is longer than 64 characters external_message_id is longer than 64 characters
Message text is empty The message to send is empty
Template field with no value: <name> The template has a {{name}} placeholder that the recipient's message_fields does not fill. With several: Template fields with no value: <a>, <b>. Only checked for template messages.
Message needs <N> SMS parts; the maximum is 10 The message needs more than 10 SMS parts (see Message Length)

A message refused by the SMS gateway when sent is also stored as FAILED, with the gateway's reason in error_message (at most 255 characters).

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)

Failure Reasons

batch_status_summary.failure_reasons breaks the batch's failed messages down by reason. It is returned wherever the batch status summary is: GET /v1/batches/{batch_id}, poll, poll_with_delta and every event.

  • A list of {"reason", "count"}, the 10 most frequent reasons first
  • reason is the message's error_message
  • Past 100 distinct reasons in one batch, further reasons are counted under Other errors
  • Absent when no message has failed
"failure_reasons": [
  {"reason": "Phone number is not valid", "count": 12},
  {"reason": "Template field with no value: name", "count": 3}
]

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, using only letters, digits, - and _.

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",
      "submitted_at": "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",
      "submitted_at": "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)

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