Send SMS
With this method you can send bulk SMS easily. This method has been extremely optimized to send more than 500.000 SMS in less than one hour.
Endpoint
https://api.gateway360.com/api/3.0/sms/send
Request
api_key | Your API Key. | ||||||||||
messages | Array of messages you want to send.
|
||||||||||
report_url | URL where you want to receive the delivery report (DLR). | ||||||||||
concat | Set to 1 if you want to allow concatenated messages (more than 160 characters). If concat is 0 (or it's not present) only first 160 chars will be sent. | ||||||||||
encoding | Set to UCS2 if you want to send messages UCS2 (70 Unicode characters per SMS) with accents, emoticons and special characters. If encoding is GSM7 (or it's not present) the SMS will be treated as GSM7 (160 non Unicode characters per SMS). The Unicode encoding is only applicable to the text of message. | ||||||||||
fake | Set to 1 if you want to simulate submitting messages, it's perfect for testing and debugging, it has no cost. |
Optional
{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}' https://api.gateway360.com/api/3.0/sms/send
$request = '{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}';
$headers = array('Content-Type: application/json');
$ch = curl_init('https://api.gateway360.com/api/3.0/sms/send');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
$result = curl_exec($ch);
if (curl_errno($ch) != 0 ){
die("curl error: ".curl_errno($ch));
}
/** Imports */
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClientBuilder;
/** End imports */
HttpClient httpClient = HttpClientBuilder.create().build();
HttpPost request = new HttpPost("https://api.gateway360.com/api/3.0/sms/send");
StringEntity params = new StringEntity(
"{" +
" \"api_key\":\"399d2b438a53ebed3db8a7d52107f846\"," +
" \"report_url\":\"http://yourserver.com/callback/script\"," +
" \"concat\":1," +
" \"messages\":[" +
" {" +
" \"from\":\"GOOD PIZZA\"," +
" \"to\":\"34666666111\"," +
" \"text\":\"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!\"," +
" \"send_at\":\"2018-02-18 17:30:00\""+
" }," +
" {" +
" \"from\":\"GOOD PIZZA\"," +
" \"to\":\"34666666112\"," +
" \"text\":\"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!\"," +
" \"send_at\":\"2018-02-18 17:30:00\""+
" }" +
" ]" +
"}");
request.addHeader("content-type", "application/json");
request.addHeader("Accept","application/json");
request.setEntity(params);
HttpResponse response = httpClient.execute(request);
require 'uri'
require 'net/http'
url = URI("https://api.gateway360.com/api/3.0/sms/send")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request.body = '{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}'
response = http.request(request)
puts response.read_body
conn = http.client.HTTPSConnection("api.gateway360.com")
payload = """{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}"""
headers = {
'content-type': "application/json",
'accept': "application/json"
}
conn.request("POST", "/api/3.0/sms/send", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.gateway360.com/api/3.0/sms/send");
var request = new RestRequest(Method.POST);
request.AddHeader("accept", "application/json");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", '{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}', ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Private Sub Command1_Click()
Dim objHTTP As Object
Dim json As String
Dim result As String
json = fJSON
Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")
URl = "https://api.gateway360.com/api/3.0/sms/send"
objHTTP.Open "POST", URl, False
objHTTP.setRequestHeader "Content-type", "application/json"
objHTTP.send (json)
result = objHTTP.responseText
Set objHTTP = Nothing
End Sub
Private Function fJSON() As String
fJSON = "{"
fJSON = fJSON & """api_key"":""399d2b438a53ebed3db8a7d52107f846"","
fJSON = fJSON & """concat"":1,"
fJSON = fJSON & """messages"":["
fJSON = fJSON & "{"
fJSON = fJSON & """from"":""GOOD PIZZA"","
fJSON = fJSON & """to"":""34666666111"","
fJSON = fJSON & """text"":""Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!"""
fJSON = fJSON & "}]}"
End Function
Response
status | The sending status of request - either "ok", "error" | ||||||||||
result | Array of results in the same order you submitted.
|
||||||||||
error_id | In case the status values "error" we will indicate you here the error id. | ||||||||||
error_msg | In case the status values "error" this param has additional information. This param should be use just for debugging. |
{
"status":"ok",
"result":[
{
"status":"ok",
"sms_id":"1a8940dc7471427db3021cde5b464444",
"custom":"test"
},
{
"status":"ok",
"sms_id":"1a8940dc7471427db3021cde5b464481",
"custom":""
}
]
}
Two messages successfully processed
{
"status":"ok",
"result":[
{
"status":"ok",
"sms_id":"1a8940dc7471427db3021cde5b464444",
"custom":"test"
},
{
"status":"error",
"error_id":"INVALID_SENDER",
"error_msg":"Sender cannot exceed 11 alphanumeric or 15 numeric characters.",
"custom":""
},
{
"status":"error",
"error_id":"INVALID_DESTINATION",
"error_msg":"Destination number must be in international format.",
"custom":"12345"
},
{
"status":"error",
"error_id":"NOT_ENOUGH_BALANCE",
"error_msg":"Your account has no funds.",
"custom":""
},
{
"status":"error",
"error_id":"INVALID_DATETIME",
"error_msg":"Invalid datetime format.",
"custom":""
}
]
}
One message successfully processed, and the rest with several errors.
{
"status":"error",
"error_id":"UNAUTHORIZED",
"error_msg":"Your API key may be invalid or your IP is blocked."
}
We didn't continue processing your request because your API Key wasn't valid.
{
"status":"error",
"error_id":"JSON_PARSE_ERROR",
"error_msg":"Your JSON was formatted incorrectly."
}
We couldn't process your request.
Errors
Error ID | Explanation |
---|---|
INVALID_CONTENT_TYPE | The content type must be: Content-Type: application/json |
JSON_PARSE_ERROR | Your JSON was formatted incorrectly or was considered otherwise improper or incomplete. Check it here. |
MISSING_PARAMS | Your request is incomplete and missing some mandatory parameters. |
BAD_PARAMS | One or more of your parameters has incorrect format or value. |
UNAUTHORIZED | Your API key may be invalid, double-check that your API key was input correctly or see if the IP is blocked in your account API settings. |
INVALID_SENDER | The sender address (from parameter) was not allowed for this message. |
INVALID_DESTINATION | Our Gateway was unable to process your destination. The number must be in MSISDN format. Check format here. |
INVALID_TEXT | The field was empty or is corrupt. |
INVALID_DATETIME | The format we were expecting was: YYYY-MM-DD HH:MM:SS |
NOT_ENOUGH_BALANCE | Your account has no funds to process this request, add credits to your account and try again. |
LIMIT_EXCEEDED | Your request has exceeded the maximum of 1000 sms requests per batch. |
Opt out
You can automatically add the unsubscription URL to your SMS. You only need to add {STOP} tag to the text of your SMS and it will be replaced with your unique unsubscription URL.
Note: please, be aware that this replacement will increase the number of characters of your SMS.
Special long characters
There are 9 special characters that are counted as 2 individual characters when GSM encoded. This could result in a message becoming longer and therefore being concatenated.The following table identifies these characters.
Symbol | Name |
---|---|
[ | Open square |
\ | Backslash |
] | Close square |
^ | Caret |
{ | Left brace |
| | Vertical bar |
} | Right brace |
~ | Tilde |
€ | Euro symbol |
Concatenated GSM messages
Also referred to as a long message, multipart message or extended message, a concatenated message is formed from several standard SMS containing a 7 byte concatenation header at the beginning of each one. Since this 7 byte header is within the message, it reduces the total size of each SMS to 153 characters each. The table below shows the maximum message length per number of SMS used for plain 7-bit messages. If you want to send a concatenated message, don’t forget you must set the parameter "concat" to value 1.
Number of SMS | Maximum Message Length |
---|---|
1 | 160 characters. |
2 | 306 characters. |
3 | 459 characters. |
4 | 612 characters. |
5 | 765 characters. |
6 | 918 characters. |
7 | 1071 characters. |
8 | 1224 characters. |
GSM Encoding
According to GSM specification, a standard SMS message can contain up to 140 bytes of data (payload). Standard latin (ISO-8859-1) character encoding represents a single character using 1 byte, which is 8 bits. Therefore, the maximum number of latin 1 characters that could be included in an sms is 140.
GSM encoding represents characters using 7 bits instead of 8. This therefore provides a maximum of 160 characters per SMS. (140 * 8 bits) / 7 bits = 160
This effectively halves the number of characters that the GSM character set can support, compared to ISO-8859-1. In order to include common characters that are usually represented using the 8th bit, these characters as well as other symbol characters must be re-mapped to a combination of lower bits. These re-mapped characters are often referred to as special characters. This re-mapping, in combination with packing 7-bit characters into 8- bit bytes is called GSM Encoding.
The below table lists the 7-bit default alphabet as specified by GSM 03.38
Hex | Character name | Character | ISO-8859-1 Hex |
---|---|---|---|
0x00 | COMMERCIAL AT | @ | 40 |
0x01 | POUND SIGN | £ | A3 |
0x02 | DOLLAR SIGN | $ | 24 |
0x03 | YEN SIGN | ¥ | A5 |
0x04 | LATIN SMALL LETTER E WITH GRAVE | è | E8 |
0x05 | LATIN SMALL LETTER E WITH ACUTE | é | E9 |
0x06 | LATIN SMALL LETTER U WITH GRAVE | ù | F9 |
0x07 | LATIN SMALL LETTER I WITH GRAVE | ì | EC |
0x08 | LATIN SMALL LETTER O WITH GRAVE | ò | F2 |
0x09 | LATIN SMALL LETTER C WITH CEDILLA (case changed) | Ç | C7 |
0x0A | Line Feed | A | |
0x0B | LATIN CAPITAL LETTER O WITH STROKE | Ø | D8 |
0x0C | LATIN SMALL LETTER O WITH STROKE | ø | F8 |
0x0D | Carriage Return | D | |
0x0E | LATIN CAPITAL LETTER A WITH RING ABOVE | Å | C5 |
0x0F | LATIN SMALL LETTER A WITH RING ABOVE | å | E5 |
0x10 | GREEK CAPITAL LETTER | Δ | |
0x11 | LOW LINE | _ | 5F |
0x12 | GREEK CAPITAL LETTER | Φ | |
0x13 | GREEK CAPITAL LETTER | Γ | |
0x14 | GREEK CAPITAL LETTER | Λ | |
0x15 | GREEK CAPITAL LETTER | Ω | |
0x16 | GREEK CAPITAL LETTER | Π | |
0x17 | GREEK CAPITAL LETTER | Ψ | |
0x18 | GREEK CAPITAL LETTER | Σ | |
0x19 | GREEK CAPITAL LETTER | Θ | |
0x1A | GREEK CAPITAL LETTER | Ξ | |
0x1B | ESCAPE TO EXTENSION | ||
0x1B0A | FORM FEED | 12 | |
0x1B14 | CIRCUMFLEX ACCENT | ^ | 5E |
0x1B28 | LEFT CURLY BRACKET | { | 7B |
0x1B29 | RIGHT CURLY BRACKET | } | 7D |
0x1B2F | REVERSE SOLIDUS (BACKSLASH) | \ | 5C |
0x1B3C | LEFT SQUARE BRACKET | [ | 5B |
0x1B3D | TILDE | ~ | 7E |
0x1B3E | RIGHT SQUARE BRACKET | ] | 5D |
0x1B40 | VERTICAL BAR | | | 7C |
0x1B65 | EURO SIGN € | A4 | (ISO-8859-15) |
0x1C | LATIN CAPITAL LETTER AE | Æ | C6 |
0x1D | LATIN SMALL LETTER AE | æ | E6 |
0x1E | LATIN SMALL LETTER SHARP S (German) | ß | DF |
0x1F | LATIN CAPITAL LETTER E WITH ACUTE | É | C9 |
0x20 | SPACE | 20 | |
0x21 | EXCLAMATION MARK | ! | 21 |
0x22 | QUOTATION MARK | " | 22 |
0x23 | NUMBER SIGN | # | 23 |
0x25 | PERCENT SIGN | % | 25 |
0x26 | AMPERSAND | & | 26 |
0x27 | APOSTROPHE | 27 | |
0x28 | LEFT PARENTHESIS | ( | 28 |
0x29 | RIGHT PARENTHESIS | ) | 29 |
0x2A | ASTERISK | * | 2A |
0x2B | PLUS SIGN | + | 2B |
0x2C | COMMA | , | 2C |
0x2D | HYPHEN-MINUS | - | 2D |
0x2E | FULL STOP | . | 2E |
0x2F | SOLIDUS (SLASH) | / | 2F |
0x30 | DIGIT ZERO | 0 | 30 |
0x31 | DIGIT ONE | 1 | 31 |
0x32 | DIGIT TWO | 2 | 32 |
0x33 | DIGIT THREE | 3 | 33 |
0x34 | DIGIT FOUR | 4 | 34 |
0x35 | DIGIT FIVE | 5 | 35 |
0x36 | DIGIT SIX | 6 | 36 |
0x37 | DIGIT SEVEN | 7 | 37 |
0x38 | DIGIT EIGHT | 8 | 38 |
0x39 | DIGIT NINE | 9 | 39 |
0x3A | COLON | : | 3A |
0x3B | SEMICOLON | ; | 3B |
0x3C | LESS-THAN SIGN | < | 3C |
0x3D | EQUALS SIGN | = | 3D |
0x3E | GREATER-THAN SIGN | > | 3E |
0x3F | QUESTION MARK | ? | 3F |
0x40 | INVERTED EXCLAMATION MARK | ¡ | A1 |
0x41 | LATIN CAPITAL LETTER A | A | 41 |
0x42 | LATIN CAPITAL LETTER B | B | 42 |
0x43 | LATIN CAPITAL LETTER C | C | 43 |
0x44 | LATIN CAPITAL LETTER D | D | 44 |
0x45 | LATIN CAPITAL LETTER E | E | 45 |
0x46 | LATIN CAPITAL LETTER F | F | 46 |
0x47 | LATIN CAPITAL LETTER G | G | 47 |
0x48 | LATIN CAPITAL LETTER H | H | 48 |
0x49 | LATIN CAPITAL LETTER I | I | 49 |
0x4A | LATIN CAPITAL LETTER J | J | 4A |
0x4B | LATIN CAPITAL LETTER K | K | 4B |
0x4C | LATIN CAPITAL LETTER L | L | 4C |
0x4D | LATIN CAPITAL LETTER M | M | 4D |
0x4E | LATIN CAPITAL LETTER N | N | 4E |
0x4F | LATIN CAPITAL LETTER O | O | 4F |
0x50 | LATIN CAPITAL LETTER P | P | 50 |
0x51 | LATIN CAPITAL LETTER Q | Q | 51 |
0x52 | LATIN CAPITAL LETTER R | R | 52 |
0x53 | LATIN CAPITAL LETTER S | S | 53 |
0x54 | LATIN CAPITAL LETTER T | T | 54 |
0x55 | LATIN CAPITAL LETTER U | U | 55 |
0x56 | LATIN CAPITAL LETTER V | V | 56 |
0x57 | LATIN CAPITAL LETTER W | W | 57 |
0x58 | LATIN CAPITAL LETTER X | X | 58 |
0x59 | LATIN CAPITAL LETTER Y | Y | 59 |
0x5A | LATIN CAPITAL LETTER Z | Z | 5A |
0x5B | LATIN CAPITAL LETTER A WITH DIAERESIS | Ä | C4 |
0x5C | LATIN CAPITAL LETTER O WITH DIAERESIS | Ö | D6 |
0x5D | LATIN CAPITAL LETTER N WITH TILDE | Ñ | D1 |
0x5E | LATIN CAPITAL LETTER U WITH DIAERESIS | Ü | DC |
0x5F | SECTION SIGN | § | A7 |
0x60 | INVERTED QUESTION MARK | ¿ | BF |
0x61 | LATIN SMALL LETTER A | a | 61 |
0x62 | LATIN SMALL LETTER B | b | 62 |
0x63 | LATIN SMALL LETTER C | c | 63 |
0x64 | LATIN SMALL LETTER D | d | 64 |
0x65 | LATIN SMALL LETTER E | e | 65 |
0x66 | LATIN SMALL LETTER F | f | 66 |
0x67 | LATIN SMALL LETTER G | g | 67 |
0x68 | LATIN SMALL LETTER H | h | 68 |
0x69 | LATIN SMALL LETTER I | i | 69 |
0x6A | LATIN SMALL LETTER J | j | 6A |
0x6B | LATIN SMALL LETTER K | k | 6B |
0x6C | LATIN SMALL LETTER L | l | 6C |
0x6D | LATIN SMALL LETTER M | m | 6D |
0x6E | LATIN SMALL LETTER N | n | 6E |
0x6F | LATIN SMALL LETTER O | o | 6F |
0x70 | LATIN SMALL LETTER P | p | 70 |
0x71 | LATIN SMALL LETTER Q | q | 71 |
0x72 | LATIN SMALL LETTER R | r | 72 |
0x73 | LATIN SMALL LETTER S | s | 73 |
0x74 | LATIN SMALL LETTER T | t | 74 |
0x75 | LATIN SMALL LETTER U | u | 75 |
0x76 | LATIN SMALL LETTER V | v | 76 |
0x77 | LATIN SMALL LETTER W | w | 77 |
0x78 | LATIN SMALL LETTER X | x | 78 |
0x79 | LATIN SMALL LETTER Y | y | 79 |
0x7A | LATIN SMALL LETTER Z | z | 7A |
0x7B | LATIN SMALL LETTER A WITH DIAERESIS | ä | E4 |
0x7C | LATIN SMALL LETTER O WITH DIAERESIS | ö | F6 |
0x7D | LATIN SMALL LETTER N WITH TILDE | ñ | F1 |
0x7E | LATIN SMALL LETTER U WITH DIAERESIS | ü | FC |
0x7F | LATIN SMALL LETTER A WITH GRAVE | à | E0 |
UCS2 Encoding
UCS2 is the Unicode format required for SMS, as opposed to the later format UTF-16. Since each UCS2 character requires 2 bytes, the SMS message length is reduced to 70 characters: 140 bytes / 2 bytes = 70 characters. You must also set the correct Data Coding Scheme value, 0 x 08 or 8 in the case of UCS2.
UCS2 encoding allows the use of emoticons in SMS and these are treated as characters so you can write it in your SMS as any other character.
Unicode messages can be concatenated. The concatenation headers reduce the characters available for content as follows:
Number of SMS | Maximum Message Length |
---|---|
1 | 70 characters. |
2 | 134 characters. |
3 | 201 characters. |
4 | 268 characters. |
5 | 335 characters. |
6 | 402 characters. |
7 | 469 characters. |
8 | 536 characters. |
@$¥èeùìòÇØøÅå _ ^}{\[~]|EÆæßE!"#%&()*+,-./0123456789:;<=>?¡ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÑܧ¿abcdefghijklmnopqrstuvwxyzäöñüà
That's all!