...
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 | ||||
---|---|---|---|---|
| ||||
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 | ||||
---|---|---|---|---|
| ||||
-- 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 | ||||
---|---|---|---|---|
| ||||
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 | ||||
---|---|---|---|---|
| ||||
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... | |
---|---|
|
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 | ||
---|---|---|
| ||
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.
...
title | Click 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 | ||
---|---|---|
Parameter | Type | Description |
Subject | String | the subject of the message |
Html | HtmlDTO | HTML part of the message (specify only the HTML inside the BODY tag) |
Text | String | the plain text part of the message |
From | EmailAddressDTO | the sender's name and email address |
To | List<EmailAddressDTO> | the list of recipientsin Toheader |
Cc | List<EmailAddressDTO> | the list of recipients in Cc header |
Bcc | List<EmailAddressDTO> | the list of recipients in Bcc |
ReplyTo | String | the email address to be added into Reply-To header |
CharSet | String | the charset of the message body |
ExtendedHeaders | List<NameValueDTO> | list of custom headers (only SMTP headers that are approved by MailUp will be added) |
Attachments | List<MessagePartDTO> | list of attachments |
EmbeddedImages | List<MessagePartDTO> | list of embedded images |
XSmtpAPI | XSmtpAPIDTO | the X-SMTPAPI header value, used for custom aggregations and configurations |
User | SmtpUserDTO | the SMTP+ user credentials: the API uses the same credentials as the SMTP relay |
HtmlDTO | ||
---|---|---|
Parameter | Type | Description |
DocType | String | the DOCTYPE directive |
Head | String | the head content |
Body | String | the body content |
BodyTag | String | the body tag, default is "< body>" |
EmailAddressDTO | ||
---|---|---|
Parameter | Type | Description |
Name | String | the name |
String | the email address |
NameValueDTO | ||
---|---|---|
Parameter | Type | Description |
N | String | the name of the parameter |
V | String | the value of the parameter |
MessagePartDTO | ||
---|---|---|
Parameter | Type | Description |
Filename | String | the file name |
ContentId | String | the Content-Id value |
Body | Array of Byte | the array of byte of the content |
XSmtpAPIDTO | ||
---|---|---|
Parameter | Type | Description |
CampaignName | String | the name used for the aggregated campaign |
CampaignCode | String | the campaign code which determines the aggregation |
Header | Boolean | add or not the MailUp header to the message |
Footer | Boolean | add or not the MailUp footer to the message |
ClickTracking | Boolean | enable click tracking |
ViewTracking | Boolean | enable view tracking |
Priority | Integer | set the priority of the message (1 high - 5 low ) |
Schedule | DateTime | schedule date and time of when it should be sent |
DynamicFields | List<NameValueDTO> | list of merge tags and recipient fields |
CampaignReport | String | name of the aggregated campaign report |
SkipDynamicFields | Boolean | skip merge tags evaluation |
SmtpUserDTO | ||
---|---|---|
Parameter | Type | Description |
Username | String | username |
Secret | String | password |
...
title | Click here to learn more about response parameters |
---|
SendResponseDTO | ||
---|---|---|
Parameter | Type | Description |
Status | String | the status of the response can be "done" or "error" |
Code | String | the result code (see the Error Code table) |
Message | String | the result message |
...
How to send an SMS
Once you have ListSecret, you can start sending text messages and authentication is no more required. The example below sends an SMS to number +393350000001
Code Block | ||||
---|---|---|---|---|
| ||||
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"}] |
...
, |
...
{
"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.
...
"isUnicode":0
} |
Expand | ||
---|---|---|
|
...
|
...
|
...
|
...
{
"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
...
|
...
the sender's name and email address
...
See the SendMessage reference for the definition of the others DTOs (EmailAddressDTO, NameValueDTO, ...)
...
title | Click here to learn more about response parameters |
---|
SendResponseDTO | ||
---|---|---|
Parameter | Type | Description |
Status | String | the status of the response can be "done" or "error" |
Code | String | the result code (see the Error Code table) |
Message | String | the result message |
...
Expand |
---|
{ "TemplateId":694, "To":[{"Name":"Max","Email":"info@example.com"}], |
...
{
"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
...
Expand | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
The request must contain the user's credentials and an optional username to query
See the SendMessage reference for the definition of SMTPUserDTO |
Expand | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
The response is given by a JSON or XML document that has the structure of a list of users information ( List<UserInfoDTO>).
|
...
{"User":{"Username":"sNNNN_NN","Secret":"..."},"Username":"sMMMM_MM"}
...
|
...
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
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).
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
On this page... | |
---|---|
|