Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 11 Next »

The MailUp transactional API for SMS does not use OAuth 2.0. Please refer to the "Getting started" section below for details.

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=

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

Once you have the value of the ListSecret parameter, you can start sending transactional text messages and basic authentication is no longer required.

The example below sends an SMS to the 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

MailUp account ID.

Integer

List ID

List identifier for the selected list within that account.

Integer

List GUID

Hash code that identifies the 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 the value specified does not exist, a new record is created in the “SMS” table, otherwise the existing one is reused.

String

Content

The text of the message. No parsing nor length check is required.

SIZE LIMIT: messages longer than 459 characters are truncated by 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

Always check subscription status on specified list (SMS_Optin table)

  • New = subscribe and send

  • Subscribed = send

  • Pending or Unsubscribed = do not send

String

DynamicFields

An array of value pairs that allows you to use merge tags in your transactional text messages.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").

It is up to you to decide if the message contains Unicode characters.

Boolean


 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.

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

301

The message was sent but the statistics are incorrect due to an error

500

302

Error delivering message to [recipient]


 

 

 

  • No labels