Overview
The MailUp transactional API for text messages (SMS) is the best choice when 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 with HTTP post, which means that you can use the "send" command as a callback function 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 introduce a level of security to these API methods, it is list specific and it can be enabled/disabled using APIs.
- You can use the GET method to check if a ListSecret already exists.
- If it does not, you can use the POST method to create it.
- 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 the ability to send transactional SMS on that list, you can use DELETE method. This method can also be used - followed by a POST method - to change an existing ListSecret value.
All these methods require Basic Authentication, hence an encoded value must be specified as header
Format: "Authorization: Basic " + Base64(username:password)
Example: username=m1234, password=hello123, Base64(m1234:hello123)=bTEyMzQ6aGVsbG8xMjM= => Authorization: Basic bTEyMzQ6aGVsbG8xMjM=
Once you have obtained the value of the ListSecret parameter:
- you can start sending transactional text messages (see example below)
- basic authentication is no longer required in those API calls
Retrieving, creating, and deleting the ListSecret parameter
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"}
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"
}
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
Sending a transactional SMS
The example below sends an SMS to the number +393350000001
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
}
Request
Click here to learn more about request parameters...
Parameter | Description | Type |
|---|
Account ID | MailUp account ID (e.g. if the main user is "m59484", then the account ID is 59848). | Integer |
List ID | MailUp list identifier for the selected account. | Integer |
List GUID | Hash code that identifies the specified MailUp list. | String |
ListSecret | Auto-generated GUID that can be used to enable or disable the use of this API. Together with the "List GUID" value, it is used to provide a security enforcement. See the sections above to learn how to get it. | String |
CampaignCode | Used to aggregate statistics on MailUp under a container text message whose name correspond to the specified text string. If the specified value does not exist, a new item is created. Otherwise the existing one is reused. | String |
Content | The text of the message to be sent. No parsing nor length check is required. SIZE LIMIT: messages longer than 670 characters are truncated by the sending engine. | String |
Recipient | The recipient’s number. Include the international prefix (either with 00 or +), or the default list prefix will be applied. (Ask for MailUp standard regex for phone numbers). Only a single phone number is allowed | String |
DynamicFields | An array of value pairs that allows you to use merge tags in your transactional text messages. | String |
IsUnicode | (optional) 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 caller is responsible for specifying if the message contains Unicode characters. | Boolean |
| Sender | (optional) Message sender. It can be numeric or alphanumeric but some restrictions may apply. As a consequence, when the sender value is not allowed, the message may be blocked or the sender may be replaced. We recommend you to specify this value only when you are confident about the delivery result (e.g. you've already tested it using the MailUp web platform), otherwise it is better to not specify this parameter in the request. In addition, in some countries the sender may be subject to local restrictions and it may be overwritten by the carriers before being delivered. You can contact us if you need support for some specific nations. | String* |
| TemplateId | (optional) reference to a MailUp message ID that has already been defined on MailUp. Do not add the "Content" parameter if you want to use TemplateId | Integer |
* max 11 chars, only letters and numbers (a-zA-Z0-9)
Response
Click here for details about error codes...
HTTP response statuses that can be returned by this API, and the corresponding error code provided by the application (inside the response).
HTTP response code | Application Code | Description |
|---|
200 | 0 | Ok. |
| 200 | 301 | The message was sent but the statistics are incorrect due to an error |
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 is not certified and cannot be used to send messages |
403 | 250 | Access denied |
500 | 300 | Operation failed: a generic error occur |
500 | 302 | Error delivering message to [recipient] |
In addition to HTTP and Application codes, a successful response has the following format:
{"Data":{"DeliveryId":1648,"Cost":1.0},"Code":"0","Description":"","State":"DONE"}
where DeliveryId is a unique identifier that can be used to retrieve the result of a specific sending (link), while Cost is the cost in credits of the sending operation.
Note: in case of a response with HTTP code = 200 and Application code = 301, the message is properly sent and a cost is charged, but the returned value of DeliveryId is 0 (zero) and it not possible to retieve the result