Note |
---|
The MailUp transactional API for SMS does not use OAuth 2.0, please . Please refer to the "Getting started" section here below for details. |
Overview
The MailUp transactional API for text messages (SMS) is the best choice when you have to send single sending individual text messages, regardless of the number of messages you need to send.
The main features of this API are the following:
- sending is immediate
- authentication is very simple
- it works on http with HTTP post, then which means that you can use the "send" command as a callback function into a in any system that supports webhooks
Getting started
Using the ListSecret parameter
In order to send an SMS you need to know the "ListSecret" value of the MailUp list you are using. "ListSecret" is an additional field that has been added to enforce the security levelintroduce a level of security to these API methods, it is list specific and it can be enabled/disabled using APIs.
...
- use the GET method to check if a ListSecret
...
- already exists.
- If it does not, you
...
...
...
- As soon as you get the value of ListSecret you can start sending text messages (refer to next paragraph) with no restrictions.
If you want to disable transactional APIsthe ability to send transactional SMS on that list, you can use DELETE method, which . This method can also be used , when - followed by a POST method , - to change the an existing ListSecret value.
All these methods require Basic Authentication, hence an encoded value must be specified as header
Code Block |
---|
Format: "Authorization: Basic " + Base64(username:password)
Example: username=m1234, password=hello123, Base64(m1234:hello123)=bTEyMzQ6aGVsbG8xMjM= => Authorization: Basic bTEyMzQ6aGVsbG8xMjM= |
...
Retrieving, creating, and deleting the ListSecret parameter
Expand |
---|
title | GET - Read ListSecret |
---|
|
Code Block |
---|
| -- 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"} |
|
...
Expand |
---|
title | DELETE - Remove ListSecret |
---|
|
Code Block |
---|
| 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 |
|
...
Sending a transactional SMS
Once you have the value of the ListSecret parameter, you can start sending transactional text messages and basic authentication is no more longer required.
The example below sends an SMS to the number +393350000001
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
} |
...
Expand |
---|
title | Click here to learn more about request parameters... |
---|
|
All fields are mandatory Parameter | Description | Type |
---|
Account ID | Console MailUp account ID. | Integer | List ID | List identifier for the selected list within that account. | 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 same list. This parameter is unique to a list within the entire MailUp system, unlike the List ID, which is unique only within a given MailUp account. | String | ListSecret | The parameter described above and used to enable or disable the use of this API (it’s an auto-generated GUID). | String | CampaignCode | Used to aggregate statistics. If a message named as specified value the value specified does not existsexist, then a new record is created in the “SMS” table, otherwise the existing one is reused. | String | Content | Message The text of the message. No parsing nor length check is required. (Messages SIZE LIMIT: messages longer than 459 characters are truncated by sending engine). | String | Recipient | The recipient’s number. Use Include the international prefix (either with 00 or +), otherwise or the default list prefix will be applied. (Ask for MailUp standard regex for phone numbers). Only a single phone number 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 It is up to you to decide if the message contains Unicode characters. | Boolean |
|
Expand |
---|
title | Click here for details about error codes... |
---|
|
This table shows possible HTTP response statuses that can be returned by the this 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 is not certified and can't cannot 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] |
|
...