Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

POST https://sendsms.mailup.com/api/v2.0/lists/1/listsecret HTTP/1.1
User-Agent: Fiddler
Authorization: Basic bTU5NDg0Ok1KOEYzUVVV
Host: sendsms.mailup.com
Content-Length: 55
Content-Type: application/json;odata=verbose;charset=utf-8

{
"ListGUID":"aafa5375-bcf1-4e06-965a-e3a98b626156"
}

Getting started

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

 

Code Block
languagegroovy
titleExample
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 perform GET, POST, DELETE on /lists/{List_ID}/listsecret resource, Basic Authentication is required.

 

You can use GET method to check if a ListSecret is already configured (if not, you should use POST method)

Code Block
languagegroovy
titleGET - 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).

 

Code Block
languagegroovy
titlePOST - 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 

Code Block
languagegroovy
titleDELETE - 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 send transactional emails with MailUp in two ways:

  • With our SMTP relay
  • Using our APIs

They provide virtually the same features. Specifically, the new transactional email API discussed in this section provides the same features that are available with the newest version of our SMTP relay, SMTP+ v2.

In addition, the performance, the aggregation policies and the usage restrictions (i.e. do not use it for promotional emails) are exactly the same as the ones enforced for SMTP+ v2.

Message header vs. JSON object

Although the features are largely the same, the way you access them is different. Parameters that are specified with message headers in SMTP+ v2, in the API are handled as fields of a JSON object that is passed to the web services. For more details about these parameters please check out the examples that are provided for SMTP+ v2

Best Practices

  • Message aggregation: avoid using message aggregation types that create several dozens of messages per day in your admin console. 
  • CampaignCode: the new CampaignCode field is a great way to aggregate messages in a way that reduces the message count and - at the same time - provides more meaningful statistics. If you don't specify the CampaignCode value, the default value for the SMTP+ user applies (this value is set in the admin console).
  • Returned value. Always check the value returned by the API: since most of the returned errors code are due to bad input parameters, any retry attempt will fail when returned code is HTTP 403.

Sending limitations

Please note that free trial accounts are limited to 25 messages sent per month. Once you become a paying customer, your sending speed and volume will be limited by the message frequency that you purchase (e.g. 5,000 messages per hour). See MailUp pricing for more.

Warnings

  • Password. If you change the password of your SMTP+ account, then any application based on it, API included, will stop working. 
  • Priority. Do not rely too much on the "Priority" field: many restrictions apply on it because its value is properly handled only at a specific stage of message workflow. There is no way to guarantee that the order based on priority value is kept at all delivery stages.
  • No API error vs. successful message delivery. Please be aware that - just like with SMTP+ - all methods used to send emails are asynchronous, hence a successful return code means that the request was correct and it has been added to a queue, but it does not guarantee message delivery. In other words, a successful return code indicates that queueing and processing was OK, but the specified recipient might still be unreachable or unsubscribed.
On this page...
Toc

 

 

Authentication

Create a SMTP+ user

To access resources and to use the methods, you must have an active account with an enabled SMTP+ user (SMTP+ users have the "sNNNNN_NN" format).

Include credentials in the request

Usename and password must be included in each request through "User" parameter .

No Format
"User":{"Username":"YourSmtpPlusUsername","Secret":"YourSmtpPlusPassword"}

An error may be returned when the SMTP+ user is blocked. In this case you could use the "ListUserInfo" method to get more details about that user.

For example, there could be a billing issue.

Resources

Messages

This section includes the methods that can be used to send transactional emails.

Use SendMessage when you need to specify a completely different content for each message, while you can use SendTemplate - and use merge tags - if you want to pick the body of an existing content and simply customize some of its parts.

The two methods provide the same level of performance: pick the one that better fits your needs. 

 

Info
titleUsing a reply-to address different from the sender address

The use of a reply-to address different from the FROM email address must be enabled by MailUp. If you need this, please contact our support team by writing an email to support@mailup.com.

SendMessage

...

This method allows sending of a transactional message to multiple recipients. This method is not intended for bulk mailings.

The message content is passed as input with HTML code or plain text. The message may also include attachments and embedded images.

...

titleClick here to learn more about request parameters

The method takes as input the document JSON or XML that has the structure MessageDTO defined in the tables below.

MessageDTO
ParameterTypeDescription
SubjectStringthe subject of the message
HtmlHtmlDTOHTML part of the message (specify only the HTML inside the BODY tag)
TextStringthe plain text part of the message
FromEmailAddressDTOthe sender's name and email address
ToList<EmailAddressDTO>the list of recipientsin Toheader
CcList<EmailAddressDTO>the list of recipients in Cc header
BccList<EmailAddressDTO>the list of recipients in Bcc
ReplyToStringthe email address to be added into Reply-To header
CharSetStringthe charset of the message body
ExtendedHeadersList<NameValueDTO>list of custom headers (only SMTP headers that are approved by MailUp will be added)
AttachmentsList<MessagePartDTO>list of attachments
EmbeddedImagesList<MessagePartDTO>list of embedded images
XSmtpAPIXSmtpAPIDTOthe X-SMTPAPI header value, used for custom aggregations and configurations
UserSmtpUserDTOthe SMTP+ user credentials: the API uses the same credentials as the SMTP relay

 

HtmlDTO
ParameterTypeDescription
DocTypeStringthe DOCTYPE directive
HeadStringthe head content
BodyStringthe body content
BodyTagStringthe body tag, default is "< body>"
EmailAddressDTO
ParameterTypeDescription
NameStringthe name
EmailStringthe email address
NameValueDTO
ParameterTypeDescription
NStringthe name of the parameter
VStringthe value of the parameter
MessagePartDTO
ParameterTypeDescription
FilenameStringthe file name
ContentIdStringthe Content-Id value
BodyArray of Bytethe array of byte of the content
XSmtpAPIDTO
ParameterTypeDescription
CampaignNameStringthe name used for the aggregated campaign
CampaignCodeStringthe campaign code which determines the aggregation
HeaderBooleanadd or not the MailUp header to the message
FooterBooleanadd or not the MailUp footer to the message
ClickTrackingBooleanenable click tracking
ViewTrackingBooleanenable view tracking
PriorityIntegerset the priority of the message (1 high - 5 low )
ScheduleDateTimeschedule date and time of when it should be sent
DynamicFieldsList<NameValueDTO>list of merge tags and recipient fields
CampaignReportStringname of the aggregated campaign report
SkipDynamicFieldsBooleanskip merge tags evaluation
SmtpUserDTO
ParameterTypeDescription
UsernameStringusername
SecretStringpassword

...

titleClick here to learn more about response parameters
SendResponseDTO
ParameterTypeDescription
StatusStringthe status of the response can be "done" or "error"
CodeStringthe result code (see the Error Code table)
MessageStringthe result message

 

...

Expand
{
"Html":
{
"DocType":null,
"Head":null,
"Body":"<div>Hello Mr. [firstname] [lastname] !!!</div><br><img width=\"600\" height=\"397\" src=\"cid:img001\">",
"BodyTag":"<body>"
},
"Text":"Hello world!!!",
"Subject":"Hello friend!",
"From":{"Name":"Test User","Email":"test@mailup.it"},
"To":[{"Name":"Massimo","Email":"info@mailup.it"}],
"Cc":[],
"Bcc":[],
"ReplyTo":null,
"CharSet":"utf-8",
"ExtendedHeaders":null,
"Attachments":null,
"EmbeddedImages":
[
{
"Filename":"Image.jpg",
"ContentId":"img001",
"Body":"..."
}
],
"XSmtpAPI":
{
"CampaignName":"Test Campaign",
"CampaignCode":"1001",
"Header":null,
"Footer":null,
"ClickTracking":null,
"ViewTracking":null,
"Priority":null,
"Schedule":null,
"DynamicFields":[{"N":"firstname","V":"Mario"},{"N":"lastname","V":"Rossi"}],
"CampaignReport":null,
"SkipDynamicFields":null
},
"User":{"Username":"sNNNNN_NN","Secret":"..."}
}

...

{
"Status":"done",
"Code":"0",
"Message":"Ok"
}

...

{
"Status":"error",
"Code":"102",
"Message":"The operation is not authorized."
}

SendTemplate

...

This method allows sending of a transactional message to multiple recipients. This method is not intended for bulk mailings.

The message content (both HTML body and plain text) is obtained by specifying the unique ID of a message previously created and stored in the MailUp admin console.

The message may also include attachments and embedded images.

...

titleClick here to learn more about request parameters
TemplateDTO
ParameterTypeDescription
SubjectStringthe subject of the message
TemplateIdIntegerNumeric ID of the MailUp message whose content has to be used. It only accepts messages that belong to the same List in which the SMTP+ user was created
FromEmailAddressDTO

the sender's name and email address

ToList<EmailAddressDTO>the list of recipientsin Toheader
CcList<EmailAddressDTO>the list of recipients in Cc header
BccList<EmailAddressDTO>the list of recipients in Bcc
ReplyToStringthe email address to be added into Reply-To header
CharSetStringthe charset of the message body
ExtendedHeadersList<NameValueDTO>list of custom headers (only SMTP headers that are approved by MailUp will be added)
AttachmentsList<MessagePartDTO>list of attachments
EmbeddedImagesList<MessagePartDTO>list of embedded images
XSmtpAPIXSmtpAPIDTOthe X-SMTPAPI header value, used for custom aggregations and configurations
UserSmtpUserDTOthe SMTP+ user credentials

 See the SendMessage reference for the definition of the others DTOs (EmailAddressDTO, NameValueDTO, ...)

...

titleClick here to learn more about response parameters
SendResponseDTO
ParameterTypeDescription
StatusStringthe status of the response can be "done" or "error"
CodeStringthe result code (see the Error Code table)
MessageStringthe result message

 

...

Expand
{
"TemplateId":694,
"Subject":"Test message from template",
"From":{"Name":"Test User","Email":"test@example.com"},
 "To":[{"Name":"Max","Email":"info@example.com"}],
"Cc":[],
"Bcc":[],
"ReplyTo":null,
"CharSet":"utf-8",
"ExtendedHeaders":null,
"Attachments":null,
"EmbeddedImages":null,
"XSmtpAPI":null,
"User":{"Username":"sNNNNN_NN","Secret":"..."}
}

...

{
"Status":"done",
"Code":"0",
"Message":"Ok"
}

...

{
"Status":"error",
"Code":"111",
"Message":"The template is not found."
}

 

Users

Use ListUserInfo to retrieve status details about current SMTP+ user or other SMTP+ users that belong to the same List of a specified MailUp account.

ListUserInfo

...


Note

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

Code Block
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


Expand
titleGET - Read ListSecret


Code Block
languagegroovy
-- 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
titlePOST - Create ListSecret


Code Block
languagegroovy
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"
}


 

Expand
titleDELETE - Remove ListSecret


Code Block
languagegroovy
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

Code Block
languagegroovy
titleRequest
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
}

Anchor
Transactional_SMS_parameters
Transactional_SMS_parameters
Request

Expand
titleClick here to learn more about request parameters

...

The request must contain the user's credentials and an optional username to query

ListUsersDTO
ParameterTypeDescription
UserSMTPUserDTOthe calling User
UsernameStringoptional User from which to read the profile, if omitted the method returns all users

See the SendMessage reference for the definition of SMTPUserDTO

Expand
titleClick here to learn more about response parameters

The response is given by a JSON or XML document that has the structure of a list of users information ( List<UserInfoDTO>). 

UserInfoDTO
ParameterTypeDescription
UsernameSMTPUserDTOthe username
IdConsolelongthe MailUp account ID
IdListlongthe List Id within that account
IsEnabledbooltrue if the user is enabled
Priorityintdefault priority setting for messages sent by this user
Notestringadmin notes
CreationDatedatetimecreation date
UpdateDatedatetimelast updated date
DomainListstringlist of allowed domains
SenderListstringlist of allowed email senders
BlockUntildatetimedate until the user is blocked
AdminBlockbooltrue if the user is blocked by the system administrator

...

{"User":{"Username":"sNNNN_NN","Secret":"..."},"Username":"sMMMM_MM"}

...

{
"Status":"done",
"Code":"0",
"Message":"Ok",
"UserList":
[
{
"Username":"sMMMM_MM",
"IdConsole":123,
"IdList":1,
"IsEnabled":true,
"Priority":3,
"Note":"",
"CreationDate":"2015-03-31T12:12:04",
"UpdateDate":"2015-03-31T12:12:34",
"DomainList":"",
"SenderList":"",
"BlockUntil":"0001-01-01T00:00:00",
"AdminBlock":false
}
]
}

...

{
"Status":"error",
"Code":"112",
"Message":"User is deleted."
}

 

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
2000Ok
4001The operation failed.
403101The input is null.
403102The operation is not authorized.
403103The user is not enabled.
403104The user is blocked.
403105The user is blocked until this date.
403106The MailUp account cannot be found.
403107The MailUp account has been suspended.
403108The MailUp account has been deleted.
403109At leastone recipient is required.
403110The sender is required.
403111The template cannot found.
403112The user has been deleted.

...

...


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

Expand
titleClick 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.

200301The 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:

Code Block
{"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