MailUp REST API Transactional
It is possible use this API send transactional Messages both for email messages and from SMS messages.
MailUp REST API Transactional : Email
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 customised 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 retrieving users.
MailUp REST API Transactional : Email : 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.
MailUp REST API Transactional : Email : 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).
MailUp REST API Transactional : Email : 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
MailUp REST API Transactional : Email : 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.
MailUp REST API Transactional : Email : Authentication
To access to the Configuration Resources of MailUp Email Rest API Transactional that allow to ,manage SMTP+ Users it is necessary use the oauth2 authentication, the same used for the MailUp Rest API Standard, based on the MailUp access credentials:
Standard OAuth 2 with access and refresh tokens. In the request you must add the token to the header ( “Authorization: Bearer {access_token}” )
MailUp Email Rest API Transactional that allow to enable and configure are API that allow to create or modify SMTP+ users.To access to the Send Resources of MailUp Email Rest API Transactional that allow to send transactional email messages it is necessary to enable the service on a List of the MailUp account, creating and enabling an SMTP+ User.
The SMTP+ User credentials is going to be the Credentials to authenticate and authorise the access to a MailUp Rest API Transactional resource.
username and password of the SMTP+ User 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.
MailUp REST API Transactional : Email : Configuration Resources
To access to the send resources of the MailUp Email Rest API Transactional, you must have an active account with an enabled SMTP+ user (SMTP+ users have the "sNNNNN_NN" name format).
You can create SMTP+ user and retrieve their credentials:
from within the MailUp web application;
calling a REST API endpoint.
It is possible to find how to use the Rest API endpoint to create and manage SMTP+ user in this link.
MailUp REST API Transactional : Email : Send resources
All the send resources of the MailUp Email Rest API to executeTransactional are accessed using SMTP+ credentials.
They allow to send transactional email messages:
specifying a completely different content for each message,
using a common model saved in MailUp customise some of its parts.
It is possible to find how to use the Rest API endpoint to send transactional email messages in this link.
MailUp REST API Transactional : SMS
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
MailUp REST API Transactional : SMS: Authentication
To access to the Configuration Resources of MailUp SMS Rest API Transactional that allow to create, manage and delete ListSecret parameter it is necessary use a standard basic authentication based on based on the MailUp access credentials.
In the request you must add the basic authentication to the request header coding BASE64 user and password ("Authorization: Basic " + Base64(username:password) ).
For example:we are using user m123456 and password “password”.
The base64 code of the string m123456:password is bTEyMzQ1NjpwYXNzd29yZA==
In the header we have to add "Authorization: Basic " bTEyMzQ1NjpwYXNzd29yZA==
To access to the Send Resources of MailUp SMS Rest API Transactional that allow to send transactional SMS messages it is necessary to enable the service on a List of the MailUp account, a ListSecret parameter.
The ListSecret parameter is going to be the Credentials to authenticate and authorise the access to a MailUp SMS Rest API Transactional send resource.
List Secret parameter must be included in each request through in the body of the request ( "ListSecret":"yyyyyyyy-ddd-eeee-ffff-3e1cb0e6e64c" ).
MailUp REST API Transactional : SMS : Configuration Resources
To access to the send resources of the MailUp SMS Rest API Transactional, you must have to enable a List Secret parameter on a List of the MailUp account calling the dedicated REST API endpoint.
It is possible to find how to use the Rest API endpoint to create and manage List Secrets in this link.
MailUp REST API Transactional : SMS: Send resources
All the send resources of the MailUp SMS Rest API Transactional are accessed using List Secret parameters.
They allow to send transactional SMS messages specifying a completely different content for each message.
It is possible to find how to use the Rest API endpoint to send transactional SMS messages in this link.