Transactional SMS using APIs

The MailUp transactional API for text messages (SMS) is the best choice when you have to send single messages, regardless 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 post, then you can use the "send" command as a callback function into a system that supports webhooks

Getting started

Security is managed by means of "ListSecret" field, which is list specific and it can be enabled/disabled using APIs

You can perform GET, POST, DELETE on /lists/{List_ID}/listsecret resource, Basic Authentication is required.

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

You can use GET method to check if a ListSecret is already configured (if not, you should use POST method). 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 APIs, you can use DELETE method, which can also be used, when followed by a POST method, to change the ListSecret value

How to send an SMS

Once you have the value of ListSecret, you can start sending text messages and authentication is no more required. The example below sends an SMS to number +393350000001

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
}

Click here to learn more about request parameters...

All fields are mandatory

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) New = subscribe and send Subscribed = send Pending or Unsubscribed =do not send	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

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]