...
- sending is immediate
- authentication is very simple
- it works on http post, then you can use the "send" command as a callback function into a system that supports webhooks
Code Block |
---|
language | groovy |
---|
title | Example |
---|
|
POST https://sendsms.mailup.com/api/v2.0/sms/{account_ID}/{List_ID} HTTP/1.1
User-Agent: Fiddler
Host: sendsms.mailup.com
Content-Type: application/json;odata=verbose;charset=utf-8
Content-Length: 428
{
"Content":"Hi [Name], welcome to [City]",
"ListGuid":"xxxxxxxx-aaa-bbbb-cccc-e3a98b626156",
"ListSecret":"yyyyyyyy-ddd-eeee-ffff-3e1cb0e6e64c",
"Recipient":"+393350000001",
"CampaignCode":"Welcome messages",
"DynamicFields":[{"N":"Name","V":"John"},{"N":"City","V":"Cremona"}],
"isUnicode":0
} |
Getting started
Security is managed by means of "ListSecret" field, which is list specific and it can be enabled/disabled using APIs
...
You can use GET method to check if a ListSecret is already configured (if not, you should use POST method)
Expand |
---|
Code Block |
---|
language | groovy |
---|
title | GET - Read ListSecret |
---|
| -- Request
GET https://sendsms.mailup.com/api/v2.0/lists/1/listsecret HTTP/1.1
User-Agent: Fiddler
Authorization: Basic aBcDeFgHiLmNoPqRsTuVz
Host: sendsms.mailup.com
Content-Length: 0
-- Response 1 (when ListSecret does not exist)
HTTP/1.1 200 OK
Content-Length: 71
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 09 Mar 2016 16:39:24 GMT
{"Data":{"ListSecret":null},"Code":"0","Description":"","State":"DONE"}
-- Response 2 (when ListSecret exists)
HTTP/1.1 200 OK
Content-Length: 105
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 09 Mar 2016 16:45:39 GMT
{"Data":{"ListSecret":""yyyyyyyy-ddd-eeee-ffff-3e1cb0e6e64c"},"Code":"0","Description":"","State":"DONE"} |
|
As soon as you get the value of ListSecret you can start sending text messages (refer to next paragraph).
Expand |
---|
Code Block |
---|
language | groovy |
---|
title | POST - Create ListSecret |
---|
| POST https://sendsms.mailup.com/api/v2.0/lists/{List_ID}/listsecret HTTP/1.1
User-Agent: Fiddler
Authorization: Basic aBcDeFgHiLmNoPqRsTuVz
Host: sendsms.mailup.com
Content-Length: 55
Content-Type: application/json;odata=verbose;charset=utf-8
{
"ListGUID":"xxxxxxxx-aaa-bbbb-cccc-e3a98b626156"
} |
|
If you want to disable transactional APIs, you can use DELETE method, which can also be used, when followed by a POST method, to change the ListSecret value
Expand |
---|
Code Block |
---|
language | groovy |
---|
title | DELETE - Remove ListSecret |
---|
| DELETE https://sendsms.mailup.com/api/v2.0/lists/1/listsecret?listGUID=xxxxxxxx-aaa-bbbb-cccc-e3a98b626156 HTTP/1.1
User-Agent: Fiddler
Authorization: Basic aBcDeFgHiLmNoPqRsTuVz
Host: sendsms.mailup.com
Content-Length: 0 |
|
How to send an SMS
Once you have ListSecret, you can start sending text messages and authentication is no more required. The example below sends an SMS to number +393350000001
...
Expand |
---|
title | Click here to learn more about request parameters... |
---|
|
Parameter | Description | Type |
---|
Account ID | Console ID | Integer | List ID | List identifier | Integer | List GUID | Hash code that identifies the list (must match with List ID) | String | List Secret | Key that must be specified on MailUp console in order to enable this API (it’s an auto-generated GUID) | String | CampaignCode | Used to aggregate statistics. If a message named as specified value does not exists, then a new record is created in “SMS” table, otherwise the existing one is reused. | String | Content | Message text. No parsing nor length check is required. (Messages longer than 459 characters are truncated by sending engine) | String | Recipient | The recipient’s number. Use international prefix (either with 00 or +), otherwise default list prefix will be applied (Ask for MailUp standard regex for phone numbers). Only a single phone is allowed Always check subscription status on specified list (SMS_Optin table) | String | IsUnicode | Boolean value indicating whether to use Western alphabets only (0 means "false"), or Eastern alphabets as well, such as Arabic, Russian, Chinese, and so on (1 means "true").
The client is in charge of deciding if the message contains Unicode | Boolean |
|
Expand |
---|
title | Click here for details about error codes... |
---|
|
This table shows possible HTTP response statuses that can be returned by the API methods and the corresponding error code provided by the application (inside the response). HTTP response code | Application Code | Description |
---|
200 | 0 | Ok. | 400 | 100 | No request found | 400 | 101 | Missing or empty parameters | 400 | 102 | ListGUID is not valid for the current account or list | 400 | 103 | ListSecret is not valid for the current account or list | 400 | 104 | SMS sender name is empty for list nr. N | 400 | 105 | Number or Prefix missing in the recipient | 400 | 106 | Recipient is invalid | 400 | 107 | Content too long | 403 | 201 | listID is not valid for the current account or list | 403 | 202 | ListGUID is not in a correct format | 403 | 203 | ListSecret is not in a correct format | 403 | 204 | Cannot send SMS to USA recipient | 403 | 205 | Sending denied: NO CREDITS | 403 | 206 | SMS number [recipient] is in optout state for list nr.[idList]. | 403 | 207 | Provided SMS sender isn't certified and can't be used to send messages | 403 | 250 | Access denied | 500 | 300 | Operation failed: a generic error occur | 500 | 301 | The message was sent but the statistics are incorrect due to an error | 500 | 302 | Error delivering message to [recipient] |
|
...