Transactional Emails using APIs

Transactional Emails using APIs

Getting started

SMTP or API? It's your choice

You can send transactional emails with MailUp in two ways:

  • With our SMTP relay (aka SMTP+)

  • Using our APIs (details below on this page)

They provide virtually the same features. In addition, performances, scalability, the aggregation policies and the usage restrictions (i.e. do not use it for promotional emails) of the APIs are exactly the same as the ones enforced for SMTP+. In fact, the two solutions share the backend architecture and the user authorization modules.  

 The main differences are the following:

  • in case you need only the basic feature, getting started with SMTP+ is usually easier because there are a lot of "ready to use" code snippets that help you implement a SMTP client   

  • with APIs you can choose between providing the whole HTML code of the message or to refer an existing email template that may be personalized with merge tags. The  SMTP relay does not support templates instead.

  • the way you access them is different. Parameters that are specified with message headers in SMTP+, 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+

  • with APIs you can take advantage of a set of additional methods for creating and retieving users

Best Practices

  • Message aggregation: avoid using message aggregation types that create several dozen messages per day in your MailUp 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

Free trial accounts: please note that free trial accounts are limited to 25 messages sent per month.

Paying customers: once you become a paying customer, your sending speed and volume will be limited by the message frequency that you have purchased (e.g. 5,000 messages per hour). See MailUp pricing for more.

Input rate limit

The number of incoming requests must not exceed the frequency of messages you have purchased (e.g. if your MailUp subscription is set to 5,000 messages per hour avoid making more than 5,000 API calls to send messages). If you exceed this threshold, submission requests are likely to be rejected

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 immediate message delivery. In other words, a successful return code indicates that queuing and processing was successful, but the specified recipient might still be unreachable or unsubscribed.

  • Caching applies. If you enable or disable an existing user, it may take up to 15' for the changes to take effect

 




User Management resources

Depending on the invoked method, user management resources may require different credentials and authentication methods.

Authentication type

References

Description

Authentication type

References

Description

OAuth 2

Authenticating with OAuth v2

Standard OAuth 2 with access and refresh tokens. In the request you must add the following header:

Authorization: Bearer {access_token}

Note: OAuth 2 requires the MailUp account credentials, not SMTP+ username and password

SMTP+ credentials in the request body

SMTP relay service

SMTP+ username and password must be included in each request through the "User" parameter inside the request body.

"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.



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" name format). You can create SMTP+ accounts and retrieve their credentials:

  1. from within the MailUp platform. See: SMTP Settings

  2. calling a REST API endpoint

In this page we explain how to create a SMTP+ account using the REST API endpoint.

Get priority codes

Description

Service method to get the enumerated types of the available priority levels

Authentication

OAuth 2

HTTP Method

GET

URL



https://services.mailup.com/api/v1.1/rest/ConsoleService.svc/Console/SmtpPlusPriorities



JSON request (example)

none

JSON response (example)







Paging and filtering (example)

none

Create a new user

Description

Before creating a SMTP+ user you have to define one or more trusted senders email and/or one or more trusted domains. To retrieve the list of trusted emails please refer to this page. Remember that you can create a SMTP+ user only if all the trusted senders you provide in the TrustedSenders field have the StatusCode property equals to 1 (Confirmed): you can find this information here.



Authentication

OAuth 2

HTTP Method

POST

URL



https://services.mailup.com/api/v1.1/rest/ConsoleService.svc/Console/List/{id_list}/SmtpPlus



JSON request (example)



{ "IsEnabled": true, "Note": "Your notes", "PriorityCode": 2, "TrustedDomains": ["yourtrusteddomain.com"], "TrustedSenders": ["you@yourtrusteddomain.com"] }



JSON response (example)











Paging and filtering (example)

none

Reset password

Description

Reset the password for the specified SMTP+ user. MailUp is in charge of creating a new password and providing it in the response body

Authentication

OAuth 2

HTTP Method

POST

URL



https://services.mailup.com/api/v1.1/rest/ConsoleService.svc/Console/List/{ID_LIST}/SmtpPlus/Reset



JSON request (example)



{ "Username": "<username>" }



JSON response (example)



200 OK { "CreationDate": "2017-08-11 07:42:45Z", "IdList": 2, "IsEnabled": true, "IsTrusted": true, "Note": "My notes", "Password": "<the new password>", "PriorityCode": 3, "SmtpPlusEncryption": "NONE, STARTTLS", "SmtpPlusPort": "25, 80, 1025-5000", "SmtpPlusServer": "fast.smtpok.com", "TrustedDomains": [], "TrustedSenders": [ "you@yourtrusteddomain.com" ], "UpdateDate": "2017-08-11 08:44:50Z", "Username": "<username>" }



If something goes wrong:

404 NotFound { "ErrorCode": "404", "ErrorDescription": "Account not found.", "ErrorName": "NotFound", "ErrorStack": "" }



Paging and filtering (example)

none



Get SMTP+ 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

Description

This method returns the list of SMTP+ users that exist in the List of a specified MailUp account. Status details of each user are provided

Authentication

SMTP+ credentials in the request body

HTTP Method

POST

URL

https://send.mailup.com/API/v2.0/users/listuserinfo 

Reference







JSON request (example)

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

JSON response (example)

Example of a successfulresponse:

{
"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
}
]
}


Example of error:

{

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

 

Send resources

All the send resources are accessed using SMTP+ credentials

 

Authentication type

References

Description

Authentication type

References

Description

SMTP+ credentials in the request body

SMTP relay service

SMTP+ Username and password must be included in each request through the "User" parameter inside the request body.

"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.



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. 



Using 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

Description

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.

Authentication

SMTP+ credentials in the request body

HTTP Method

POST

URL

https://send.mailup.com/API/v2.0/messages/sendmessage

Reference







 JSON request (example)





JSON response (example)

Example of a successful response:

{

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

Example of error:

{

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

SendTemplate

Description

This method allows sending of a transactional message to multiple recipients, taking advantage of placeholders to customize content. 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.

Only lowercase placeholders must be used in the referenced messages. If you use capital letters (e.g. "Dear [FirstName]", the text is not replaced.



If you edit an email message already sent, wait 15 minutes before sending out the modified message. This time is needed to update the cache

Authentication

SMTP+ credentials in the request body

HTTP Method

POST

URL

https://send.mailup.com/API/v2.0/messages/sendtemplate 

Reference







JSON request (example)





JSON response (example)

Example of a successfulresponse:

{

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


Example of error:

{

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

 

Error codes

This table lists the response codes that can be returned by the API methods whose authentication method consists of SMTP+ credentials in the request body.



HTTP response code

Application Code

Description

HTTP response code

Application Code

Description

200

0

Ok

400

1

The operation failed.

403

101

The input is null.

403

102

The operation is not authorized.

403

103

The user is not enabled.

403

104

The user is blocked.

403

105

The user is blocked until this date.

403

106

The MailUp account cannot be found.

403

107

The MailUp account has been suspended.

403

108

The MailUp account has been deleted.

403

109

At least one recipient is required.

403

110

The sender is required.

403

111

The template cannot found.

403

112

The user has been deleted.