Outbound SMS
When you send an SMS to a phone number belonging to an end user's device you are sending an Outbound SMS. Historically, this was and still is referred to as a Mobile Terminated (MT) SMS, though nowadays an SMS is not always sent to a mobile device. In an Outbound SMS, you can set the ''from'' field with whatever you have requested with Messangi, either a Long Code, Short Code, alphanumeric shortcode, or virtual number.
Outbound SMS API allows you to send SMS messages to and from any country in the world through a REST API. Each message is identified by a unique random ID so that users can always check the status of a message using the given endpoint. It is a type of API that allows your business to integrate SMS (Short Message Service) messaging into your existing software platforms. That is, this API is a well-defined software interface which enables code to send short messages via a SMS Gateway.
As the infrastructures for SMS communications and the internet are mostly divided, SMS APIs are often used to 'bridge the gap' between telecommunications carrier networks and the wider web. SMS APIs are used to allow web applications to easily send and receive text messages quickly and easily through logic written for standard web frameworks. Our APIs make it possible for your business to operate 24/7, providing customer notifications and information even outside business hours and Keeping customers updated of the new offerings and deals about your company aids in the growth of your company.
This API helps you to quickly create and configure sending SMS messages to your customers globally in real time and ability to see a list of the messages sent. The main advantage of our API is its simplicity of implementation, easy and simple way to use!
-
Send SMS messages using local numbers.
-
See each SMS text message status sent in real time.
In order to maintain customer engagement, you may send messages to keep your customers up to date on the most recent information, status, or alerts from your company. In this tutorial, we’ll show you how to send an SMS to any phone number.
Take your global SMS messaging to the next level with a platform built for scale, speed, and deliverability.
Before sending your first SMS message, you must set up the short code or long code from which the message will be sent.
A Short Code is a special telephone number designed for high-throughput, two-way messaging. Short codes are used to send and receive SMS messages to and from mobile phones. That is, an SMS shortcode is a 5 digit number to which an SMS text message can be sent. Shortcodes are often used by businesses to allow customers to opt-in to their SMS campaigns, alert services, or to enter SMS competitions.
A Long Code is a standard phone number used to send and receive voice calls and SMS messages. Phone numbers are typically called “long codes” (10-digit numbers in many countries) when comparing them with SMS short codes (5-6 digit numbers). With a long code, you can only send one message per second. Therefore long code text marketing does not work if you want to message groups of more than 200 people.
If you’re choosing between a long and short code for your brand’s SMS number, consider using a short code since it can provide higher throughputs, faster messaging, and help you drive better customer engagement.
When it comes to mobile engagement applications there are some important acronyms and terminology that would be helpful to memorize. The world of SMS is full of acronyms that might confuse you, especially if more than one term is used for the same thing. So, we decided to help you learn this specific language before sending your first SMS text message to your customers. Two important terms that you may find mentioned regularly are MT and MO.
A mobile message routed from a client or an application and delivered to the end user’s mobile phone is called a MT (Mobile Terminated). The word Terminated means that the message is terminated (delivered) on a mobile device. It is also known as an Outbound SMS. For example, you send the following SMS message to your subscribers : “Show this voucher for 10% off your next order”.
The term MO (mobile originated) message stands for a mobile message routed from an end user’s mobile device and delivered to a mobile phone or an application. More precisely, this is a message that a customer/subscriber sends from a mobile phone to a web application or platform. For example, you send the following SMS message to your customer waiting for a response from them: “Send PIZZA to 7878 for 30% off your next order!
In this API, we use the term MT because we will only send an SMS message to customers. If you desire to receive SMS messages (MO), go to the Receive SMS section.
NOTE
The destination address ("to") of the message must be specified in E.164 format → (‘+’ and a country code). The plus sign prefix of the format is optional.
E.164 format: An ITU recommendation for the International Public Telecommunications Numbering Plan, used in the world's Public Switched Telephone Network (PSTN). It defines a common format for international phone numbers prefixed with a ( + ) sign followed by a sequence of up to 15 digits, made up of a Country Code (1 to 3 digits) and a Subscriber Number that includes the area code (maximum 12 digits).
Sending SMS message
SMS APIs connect telecom carriers to the internet, avoiding the necessity of using a platform or software “middleman” to affect this functionality. After you integrate an SMS API, logging in manually to send SMS messages becomes a thing of the past.
When you send an SMS text message, the request body contains the following data:
HTTP Request : POST / messages
{
"from": "12345",
"text": "text demo",
"to": "+580000000005"
}
The parameters presented in the request body example when sending the SMS text message are the following:
| Parameter | Required | Description |
|---|---|---|
| from | Yes | Source address of the message. Specifies the Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number that will be used to originate and send the SMS message. Any of these codes will appear in the handset as the source of the text message. Virtual numbers will translate to a local shortcode depending on the destination carrier. If you don't have one assigned yet please contact our support team to request one. |
| text | Yes | Content of the SMS message that will be sent to the end user. The maximum length of a short message text is 160 characters using the default GSM 03.38 alphabet. If you use any character that is not in the default alphabet, the message will be encoded in Unicode and will be divided in segments of a maximum of 70 characters each. For example, if you include an emoji in your message and the message is 150 characters long, it will be divided into three segments: the first one with 70 characters, the second one with 70 characters and the third one with just 10 characters. You will be charged per segment, not per message. |
| to | Yes | Destination address of the message. This is the cell phone number where you want to send your message to. The destination address must be specified in E.164 format → (‘+’ and a country code). The plus sign prefix of the format is optional. |
| requestDR | No | Request a Delivery Receipt to the carrier.
By default is |
| connection | No | Name of the connection to indicate which carrier to send the message to. This is only used in cases where there are ambiguities between the destination carriers you are allowed to send to. If you need to indicate this parameter, Messangi will provide you a list of connection names to use for your case. |
| callbacks | No | Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your subscribers, you need to specify your endpoint. Your endpoint must have a HTTP POST access method and receive a JSON body. The URL is the external callback where the events of the SMS message will be registered and published. The following SMS message status sent to your callback URL will be the status to be recorded in the callback once the message has been sent:
To notify the status of the message delivery through a callback, the To know the parameters that will be registered and sent to your callback URL in JSON format go to the Callback URL (MT) section |
| No | Email associated with destination. |
|
| type | No |
By default is |
| externalId | No | Alphanumeric identifier that can be used for reporting purposes. For instance, you could set the name or ID of the action that originated this SMS message so you can then identify where this API call is coming from. This is an identifier you can use to identify your messages uniquely. Typical applications are to assign a different identifier per message or per group of messages, like a campaign identifier. This identifier will be sent back to you if you request callbacks containing status changes of the messages you send. |
| clientId | No | Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send. |
When you sent the SMS text message, the response body contains the following data:
{
"meta": {
"timestamp": 1629174338140,
"transactionId": "c4cdd080-fbbf-46e3-aff1-311e21f5048c"
},
"data": {
"id": "611b3a42c5f7904590c17d1f",
"from": "12345",
"text": "text demo",
"to": "+580000000005",
"requestDR": true,
"type": "MT",
"owner": "[email protected]",
"operator": "[email protected]",
"status": "QUEUE",
"date": "2021-08-17T04:25:38.117592194Z"
}
}
The parameters presented in the response body example when sending the SMS text message are the following:
| Parameter | Description |
|---|---|
| data | Data contained in the SMS message. |
| data.id | Unique identifier of the SMS message. |
| data.from | Source address of the message. Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number that will be used to originate and send the SMS message. Any of these codes will appear in the handset as the source of the text message. Virtual numbers will translate to a local shortcode depending on the destination carrier. |
| data.text | Content of the SMS message sent to the end user. The maximum length of a short message text is 160 characters using the default GSM 03.38 alphabet. If you use any character that is not in the default alphabet, the message will be encoded in Unicode and will be divided in segments of a maximum of 70 characters each. For example, if you include an emoji in your message and the message is 150 characters long, it will be divided into three segments: the first one with 70 characters, the second one with 70 characters and the third one with just 10 characters. You will be charged per segment, not per message. |
| data.to | Destination address of the message. This is the cell phone number of the recipient to which the message was sent. The destination address must be specified in E.164 format → (‘+’ and a country code). The plus sign prefix of the format is optional. |
| data.owner | Owner or creator of the SMS transaction. |
| data.operator | User who is a member of the owner or creator of the SMS message. |
| data.status | When the SMS message is sent, the system assigns one of the following possible status to an SMS message:
|
| data.date | Date when the last update or status change. |
| data.requestDR | Optional. Request a Delivery Receipt to the carrier.
By default is |
| data.connection | Optional. Name of the connection to indicate which carrier to send the message to. This is only used in cases where there are ambiguities between the destination carriers you are allowed to send to. If you need to indicate this parameter, Messangi will provide you a list of connection names to use for your case. |
| data.callbacks | Optional. Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your subscribers, you need to specify your endpoint. Your endpoint must have a HTTP POST access method and receive a JSON body. The URL is the external callback where the events of the SMS message will be registered and published. The following SMS message status sent to your callback URL will be the status to be recorded in the callback once the message has been sent:
To notify the status of the message delivery through a callback, the To know the parameters that will be registered and sent to your callback URL in JSON format go to the Callback URL (MT) section |
| data.email | Optional. Email associated with destination. |
| data.type | Optional. By default is |
| data.externalId | Optional. Alphanumeric identifier that can be used for reporting purposes. For instance, you could set the name or ID of the action that originated this SMS message so you can then identify where this API call is coming from. This is an identifier you can use to identify your messages uniquely. Typical applications are to assign a different identifier per message or per group of messages, like a campaign identifier. This identifier will be sent back to you if you request callbacks containing status changes of the messages you send. |
| data.clientId | Optional. Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send. |
Sending Batch SMS messages
With this endpoint, you can send multiple SMS messages in one POST call.
In your request body, include the following parameters to send multiple SMS messages:
HTTP Request: POST v3/messages/batch
{
"from":"12345",
"text":"Hi {0}, your balance is ${1}",
"to":[
{
"to:":"+525500000000",
"params":[
"Elizabeth",
10.65
]
},
{
"to:":"+525511111111",
"params":[
"Joshua",
20.5
]
}
],
"type":"MT"
}
The parameters presented in the request body example when sending the SMS text message are the following:
| Parameter | Required | Description |
|---|---|---|
| from | Yes | Source address of the message. Specifies the Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number that will be used to originate and send the SMS message. Any of these codes will appear in the handset as the source of the text message. Virtual numbers will translate to a local shortcode depending on the destination carrier. If you don't have one assigned yet please contact our support team to request one. |
| text | Yes | Content of the SMS message that will be sent to the end user. The maximum length of a short message text is 160 characters using the default GSM 03.38 alphabet. If you use any character that is not in the default alphabet, the message will be encoded in Unicode and will be divided in segments of a maximum of 70 characters each. For example, if you include an emoji in your message and the message is 150 characters long, it will be divided into three segments: the first one with 70 characters, the second one with 70 characters and the third one with just 10 characters. You will be charged per segment, not per message. |
| to | Yes | Array of destination addresses containing end users you want to send the message. |
| to.to | Yes | Destination address of the message. This is the cell phone number where you want to send your message to. The destination address must be specified in E.164 format → (‘+’ and a country code). The plus sign prefix of the format is optional. |
| to.params | Yes | Only applies if the content of the SMS message ( Array of personalized fields (placeholders) values containing the SMS message. Set placeholder/s values in order (position) of how each placeholder was defined in the SMS message. For example, from the |
| requestDR | No | Request a Delivery Receipt to the carrier.
By default is |
| connection | No | Name of the connection to indicate which carrier to send the message to. This is only used in cases where there are ambiguities between the destination carriers you are allowed to send to. If you need to indicate this parameter, Messangi will provide you a list of connection names to use for your case. |
| callbacks | No | Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your subscribers, you need to specify your endpoint. Your endpoint must have a HTTP POST access method and receive a JSON body. The URL is the external callback where the events of the SMS message will be registered and published. The following SMS message status sent to your callback URL will be the status to be recorded in the callback once the message has been sent:
To notify the status of the message delivery through a callback, the To know the parameters that will be registered and sent to your callback URL in JSON format go to the Callback URL (MT) section |
| No | Email associated with destination. |
|
| type | No |
By default is |
| externalId | No | Alphanumeric identifier that can be used for reporting purposes. For instance, you could set the name or ID of the action that originated this SMS message so you can then identify where this API call is coming from. This is an identifier you can use to identify your messages uniquely. Typical applications are to assign a different identifier per message or per group of messages, like a campaign identifier. This identifier will be sent back to you if you request callbacks containing status changes of the messages you send. |
| clientId | No | Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send. |
When you sent the SMS text messages, the response body contains the following data:
{
"meta": {
"timestamp": 1597166699457,
"transactionId": "70169d77-c165-35b8a3af96fb",
"explain": "a descriptive text"
},
"data": {
"ids": [
{
"id": "507f1f77b",
"mobile": "+525500000000"
},
{
"id": "507Abg71A",
"mobile": "+525511111111"
}
],
"from": "12345",
"text": "Hi {0}, your balance is ${1}",
"type": "MT",
"owner": "owner",
"operator": "operator",
"status": "QUEUE",
"date": "2020-06-22T15:06:37.909584Z"
}
}
The parameters presented in the response body example when sending the SMS text messages are the following:
| Parameter | Description |
|---|---|
| data | Data contained in the SMS message. |
| data.ids | Array containing the destination address of each end user and the unique identifier (id) of each message sent. |
| data.ids.id | Unique identifier of the SMS message. |
| data.ids.mobile | Destination address of the message. This is the cell phone number of the end user who received the sent message. The destination address is specified in E.164 format → (‘+’ and a country code). The plus sign prefix of the format is optional. |
| data.invalidNumber | Array containing invalid destination mobile numbers by validation format. |
| data.from | Source address of the message. Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number that will be used to originate and send the SMS message. Any of these codes will appear in the handset as the source of the text message. Virtual numbers will translate to a local shortcode depending on the destination carrier. |
| data.text | Content of the SMS message sent to the end user. The maximum length of a short message text is 160 characters using the default GSM 03.38 alphabet. If you use any character that is not in the default alphabet, the message will be encoded in Unicode and will be divided in segments of a maximum of 70 characters each. For example, if you include an emoji in your message and the message is 150 characters long, it will be divided into three segments: the first one with 70 characters, the second one with 70 characters and the third one with just 10 characters. You will be charged per segment, not per message. |
| data.owner | Owner or creator of the SMS transaction. |
| data.operator | User who is a member of the owner or creator of the SMS message. |
| data.status | When the SMS message is sent, the system assigns one of the following possible status to an SMS message:
|
| data.date | Date when the last update or status change. |
| data.requestDR | Optional. Request a Delivery Receipt to the carrier.
By default is |
| data.connection | Optional. Name of the connection to indicate which carrier to send the message to. This is only used in cases where there are ambiguities between the destination carriers you are allowed to send to. If you need to indicate this parameter, Messangi will provide you a list of connection names to use for your case. |
| data.callbacks | Optional. Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your subscribers, you need to specify your endpoint. Your endpoint must have a HTTP POST access method and receive a JSON body. The URL is the external callback where the events of the SMS message will be registered and published. The following SMS message status sent to your callback URL will be the status to be recorded in the callback once the message has been sent:
To notify the status of the message delivery through a callback, the To know the parameters that will be registered and sent to your callback URL in JSON format go to the Callback URL (MT) section |
| data.email | Optional. Email associated with destination. |
| data.type | Optional. By default is |
| data.externalId | Optional. Alphanumeric identifier that can be used for reporting purposes. For instance, you could set the name or ID of the action that originated this SMS message so you can then identify where this API call is coming from. This is an identifier you can use to identify your messages uniquely. Typical applications are to assign a different identifier per message or per group of messages, like a campaign identifier. This identifier will be sent back to you if you request callbacks containing status changes of the messages you send. |
| data.clientId | Optional. Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send. |
Example
In the following example, we are going to send an SMS message.
These instructions describe how you can send your first SMS message! Using cURL calls.
Before you can start using the Outbound SMS API, you need to complete the following steps:
- Get user credentials: you must contact your account manager or support team to obtain user credentials. Once the email is sent, the support team will send you the access credentials (username : your email address and password.)
- Get your API Key: your account manager will provide the API Key.
- Make sure you have cURL installed on your machine.
Your API call must have the following components:
- A host -> The host requests are always
https://elastic.messangi.me - An Authorization header -> Your API Key must be included in the Authorization header.
- A request -> When submitting data to a resource via POST or PUT, you must submit your payload in JSON.
Send an SMS
The steps to send an SMS message using the Outbound SMS API are the following:
Copy the curl example above.
Paste the curl call into your favorite text editor.
Copy your API key and paste it in the
Authorizationheader. In the example above, replaceYOUR_API_KEYwith your API key.-
In the
datasection, specify the following required parameters:Parameter Description from Specifies the Short or Long code that will be used to originate and send the SMS message. If you don't have one assigned yet please contact our support team to request one. text The content of the SMS message that will be sent to the end user. to Determines the destination phone number for your SMS message. requestDR Optional. Request a Delivery Receipt to the carrier.
true: Operator notifies the state of a message while it is in transit to its destination. We recommend you use this option.false: Operator won't notify the state of a message while it is in transit to its destination.By default is
falsetype Optional. MT: Message sent from the mobile SMS provider system to the end user's mobile phone Copy the code and paste it in your terminal command.
Press Enter.
Check the response body and verify the SMS message sent to your recipient.
All responses are returned in JSON format. We specify this by sending the Content-Type header.
Updated 15 days ago