SMS v2

  1. Home
  2. API Library
  3. SMS v2
High-Quality SMS with a custom sender, real-time delivery reports, and instant sending.

Integrate via API a global professional SMS service, ideal for two-factor authentication (2FA), notifications and alerts, appointment reminders, and critical communications, ensuring security, speed, and complete tracking of every message.

All the knowledge you need

Here you can find some advice to consider to approach this API. If you prefer, we provide code samples, OAS3 documentation, the ability to try the API live via the Swagger UI or import the entire collection into Postman. We also offer a Sandbox environment where you can experiment with all kinds of requests completely free of charge.

Useful tips to start with SMS v2

Get the token in the appropriate section before you start.

Use the the online tool or generate it via API. Set the expire date, a usefull name and now add a bunch of scopes to limit the possible actions your token can do.
Read more on oauth API Manage my tokens

Send SMS Messages

Methods for sending SMS messages.

Send SMS Worldwide
POST /WW-messages
Creates and queues a new SMS message for worldwide sending. Costs are calculated after sending.

Send SMS to Italy
POST /IT-messages
Creates and queues a new SMS message specifically for Italy.

Send SMS to Spain
POST /ES-messages
Creates and queues a new SMS message specifically for Spain.

Send OTP verification code
POST /otp
Generates and sends a secure OTP code via SMS. The message is automatically translated.

Message Consultation

Methods to retrieve the list and details of sent messages.

List Sent Messages
GET /messages
Returns a paginated list of messages sent from your account.

Get Message Details
GET /messages/{id}
Returns the details of a specific message via its ID.

API docs by Redocly

Gateway SMS (1.3.0)

URL: https://openapi.it/en/support License: Apache 2.0 Terms of Service

The Gateway SMS API by Openapi provides a robust and scalable solution for integrating professional SMS messaging into your applications. Our service is designed to handle high volumes of messages with precision, offering dedicated endpoints for specific regions like Italy and Spain, as well as a Worldwide endpoint for global reach.

Each request undergoes a rigorous validation process that includes syntax checking for E.164 formats, character encoding detection (GSM-7 or UCS-2), and automatic segmentation for long messages. We prioritize security and compliance: the system automatically scans content for forbidden words to prevent abuse and ensures that all messages comply with legal requirements.

Developers can benefit from advanced features such as 'Dry Run' for testing without incurring costs, and real-time Webhook callbacks that provide immediate updates on delivery status. Messages have a maximum expiration time of 48 hours; if a message cannot be delivered within this window, its status will change to EXPIRED. Billing is transparent and dynamic; while regional messages have fixed rates, worldwide delivery costs are calculated post-sending to ensure the best market price. Please note that maintaining a minimum credit balance is required for worldwide operations, and strict penalties apply for policy violations to ensure the highest quality of service for all users.

First time here? Generate a new access token

Messages

Operations for sending and retrieving SMS messages.

Send a new SMS message (Worldwide)

Creates and queues a new SMS message for worldwide sending. Please note that for this endpoint, the message cost will be calculated and charged only after the message has been sent. The final price varies depending on the recipient's operator.

If the user has an active subscription plan, the message parts will be deducted from the available bundle before charging any remaining balance from the wallet.

To send a message via this endpoint, you must have a minimum credit on your account equal to 1 EUR multiplied by the number of message parts (messageCount) in case a bundle is not available or insufficient.

IMPORTANT: If the message content or sender contains forbidden words, the message will be blocked, the account will be blocklisted, and a penalty fee of 1 EUR per message part will be charged.

Authorizations:
bearerAuth
Request Body schema: application/json

Data of the message to be sent.

sender
string or null [ 3 .. 11 ] characters
Default: "Openapi"

The message sender. Must be an alphanumeric Alias (between 3 and 11 chars, spaces allowed) and cannot be purely numeric. If null or empty, 'Openapi' will be used as the default sender.

recipient
required
string

The recipient's number in international E.164 format.

message
required
string

The text of the message to be sent. Segmentation is handled automatically. GSM-7 encoding allows up to 160 characters per part (153 if multi-part), while UCS-2 allows up to 70 characters (67 if multi-part).

object (MessageOptions)
object (CallbackOptions)

This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.

Responses

Response Schema: application/json
object (MessageResponse)

Object representing a message.

Callbacks

Request samples

Content type
application/json
{
  • "sender": "MyCompany",
  • "recipient": "+393331234567",
  • "message": "Hello! This is a test message.",
  • "options": {
    },
  • "callback": {
    }
}

Response samples

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

Callback payload samples

Callback
POST: Callback for message status updates
Content type
application/json
{
  • "id": "633aabe3e4a9a0e69811ad7f",
  • "username": "string",
  • "state": "NEW",
  • "sender": "string",
  • "recipient": "string",
  • "internationalPrefix": "39",
  • "countryCode": "IT",
  • "message": "string",
  • "encoding": "GSM-7",
  • "charactersCount": 0,
  • "messageCount": 0,
  • "price": 0,
  • "totalPrice": 0,
  • "blocklisted": true,
  • "blocklistedReason": "string",
  • "options": {
    },
  • "callback": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "deliveredAt": "2019-08-24T14:15:22Z"
}

Send a new SMS message (Italy)

Creates and queues a new SMS message for sending specifically to Italy. Applies country-specific rules and pricing.

IMPORTANT: If the message content or sender contains forbidden words, the message will be blocked, the account will be blocklisted, and the cost of the message will be charged.

Authorizations:
bearerAuth
Request Body schema: application/json

Data of the message to be sent.

sender
string or null [ 3 .. 11 ] characters
Default: "Openapi"

The message sender. Must be an alphanumeric Alias (between 3 and 11 chars, spaces allowed) and cannot be purely numeric. If null or empty, 'Openapi' will be used as the default sender.

recipient
required
string

The recipient's number in international E.164 format.

message
required
string

The text of the message to be sent. Segmentation is handled automatically. GSM-7 encoding allows up to 160 characters per part (153 if multi-part), while UCS-2 allows up to 70 characters (67 if multi-part).

object (MessageOptions)
object (CallbackOptions)

This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.

Responses

Response Schema: application/json
object (MessageResponse)

Object representing a message.

Callbacks

Request samples

Content type
application/json
{
  • "sender": "MyCompany",
  • "recipient": "+393331234567",
  • "message": "Hello! This is a test message.",
  • "options": {
    },
  • "callback": {
    }
}

Response samples

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

Callback payload samples

Callback
POST: Callback for message status updates
Content type
application/json
{
  • "id": "633aabe3e4a9a0e69811ad7f",
  • "username": "string",
  • "state": "NEW",
  • "sender": "string",
  • "recipient": "string",
  • "internationalPrefix": "39",
  • "countryCode": "IT",
  • "message": "string",
  • "encoding": "GSM-7",
  • "charactersCount": 0,
  • "messageCount": 0,
  • "price": 0,
  • "totalPrice": 0,
  • "blocklisted": true,
  • "blocklistedReason": "string",
  • "options": {
    },
  • "callback": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "deliveredAt": "2019-08-24T14:15:22Z"
}

Send a new SMS message (Spain)

Creates and queues a new SMS message for sending specifically to Spain. Applies country-specific rules and pricing.

IMPORTANT: If the message content or sender contains forbidden words, the message will be blocked, the account will be blocklisted, and the cost of the message will be charged.

Authorizations:
bearerAuth
Request Body schema: application/json

Data of the message to be sent.

sender
string or null [ 3 .. 11 ] characters
Default: "Openapi"

The message sender. Must be an alphanumeric Alias (between 3 and 11 chars, spaces allowed) and cannot be purely numeric. If null or empty, 'Openapi' will be used as the default sender.

recipient
required
string

The recipient's number in international E.164 format.

message
required
string

The text of the message to be sent. Segmentation is handled automatically. GSM-7 encoding allows up to 160 characters per part (153 if multi-part), while UCS-2 allows up to 70 characters (67 if multi-part).

object (MessageOptions)
object (CallbackOptions)

This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.

Responses

Response Schema: application/json
object (MessageResponse)

Object representing a message.

Callbacks

Request samples

Content type
application/json
{
  • "sender": "MyCompany",
  • "recipient": "+393331234567",
  • "message": "Hello! This is a test message.",
  • "options": {
    },
  • "callback": {
    }
}

Response samples

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

Callback payload samples

Callback
POST: Callback for message status updates
Content type
application/json
{
  • "id": "633aabe3e4a9a0e69811ad7f",
  • "username": "string",
  • "state": "NEW",
  • "sender": "string",
  • "recipient": "string",
  • "internationalPrefix": "39",
  • "countryCode": "IT",
  • "message": "string",
  • "encoding": "GSM-7",
  • "charactersCount": 0,
  • "messageCount": 0,
  • "price": 0,
  • "totalPrice": 0,
  • "blocklisted": true,
  • "blocklistedReason": "string",
  • "options": {
    },
  • "callback": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "deliveredAt": "2019-08-24T14:15:22Z"
}

Send an OTP verification message

Generates a secure OTP code and sends it via SMS to the recipient using 'OTP MOBILE' as the default sender. The message body is automatically translated based on the recipient's country. Pricing follows the Worldwide (WW) model.

Authorizations:
bearerAuth
Request Body schema: application/json

Data for the OTP message.

recipient
required
string

The recipient's number in international E.164 format.

alphanumeric
boolean
Default: false

If set to 'true', the generated OTP will be alphanumeric. If 'false' (default), it will be purely numeric.

length
integer [ 4 .. 10 ]
Default: 5

The length of the OTP code (min 4, max 10).

cacheSeconds
integer [ 0 .. 600 ]
Default: 0

The number of seconds within which the same OTP code will be reused for the same recipient (max 600).

object (MessageOptions)
object (CallbackOptions)

This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.

Responses

Response Schema: application/json
object (OTPMessageResponse)

Object representing a message.

Callbacks

Request samples

Content type
application/json
{
  • "recipient": "+393331234567",
  • "alphanumeric": false,
  • "length": 5,
  • "cacheSeconds": 0,
  • "options": {
    },
  • "callback": {
    }
}

Response samples

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

Callback payload samples

Callback
POST: Callback for OTP status updates
Content type
application/json
{
  • "id": "633aabe3e4a9a0e69811ad7f",
  • "username": "string",
  • "state": "NEW",
  • "sender": "string",
  • "recipient": "string",
  • "internationalPrefix": "39",
  • "countryCode": "IT",
  • "message": "string",
  • "encoding": "GSM-7",
  • "charactersCount": 0,
  • "messageCount": 0,
  • "price": 0,
  • "totalPrice": 0,
  • "blocklisted": true,
  • "blocklistedReason": "string",
  • "options": {
    },
  • "callback": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "deliveredAt": "2019-08-24T14:15:22Z",
  • "isOtp": true,
  • "otp": "5F8A2",
  • "otpOptions": {
    }
}

Retrieve the list of sent messages

Returns a paginated list of messages sent from your account.

Authorizations:
bearerAuth
query Parameters
skip
integer
Default: 0

Number of messages to skip for pagination.

limit
integer
Default: 100

Maximum number of messages to return.

Responses

Response Schema: application/json
Array of objects (MessageResponse)

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://sms.openapi.com/messages?skip=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve a single message

Returns the details of a specific message via its ID.

Authorizations:
bearerAuth
path Parameters
id
required
string

The unique ID of the message to retrieve.

Responses

Response Schema: application/json
object (MessageResponse)

Object representing a message.

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://sms.openapi.com/messages/%7Bid%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    }
}
Web Service Revision: 2.0.0