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.
from Originator address (sender). Up to 15 numeric or 11 alphanumeric characters. All characters non-ASCII will be replaced with its equivalent if exist any (á => a), empty in another case.
to Destination mobile number in international format. Country code must be included.Ex: to=447525812121 when sending to UK.
text Body of the text message (with a maximum length of 459 characters)
custom Include any reference string for your reference. Useful for your internal reports. Maximum 32 alphanumeric characters.
send_at When this message should be sent as timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately.
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.
Mandatory
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
You can send up to 1,000 SMS per request. That's almost 1 Million SMS/hour!

Response

status The sending status of request - either "ok", "error"
result Array of results in the same order you submitted.
status The status of the message - either "ok", "error"
sms_id Operator message id (with a maximum length of 32 characters). This is helpful for delivery reports.
custom Custom field sent in request.
error_id In case the status values "error" this param gives you the error id.
error_msg In case the status values "error" this param has additional information. This param should be use just for debugging.
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.
200 OK
{
    "status":"ok",
    "result":[
        {
            "status":"ok",
            "sms_id":"1a8940dc7471427db3021cde5b464444",
            "custom":"test"
        },
        {
            "status":"ok",
            "sms_id":"1a8940dc7471427db3021cde5b464481",
            "custom":""
        }
    ]
}
Two messages successfully processed
200 OK
{
    "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.
401 Unauthorized
{
    "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.
400 Bad Request
{
    "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.

NOTE
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.
Once you have everything set up, try to send messages with weird characters like this one:
@$¥èeùìòÇØøÅå _ ^}{\[~]|EÆæßE!"#%&()*+,-./0123456789:;<=>?¡ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÑܧ¿abcdefghijklmnopqrstuvwxyzäöñüà

That's all!