When should I be interested in sending transactional messages?

if your use case is at least one of the following:

You want to send emails/SMS with highly personalized content to your subscribers (e.g. job offers)
You want to implement a one-to-one notification (e.g. password reminder)
Sending bulk promotional messages is not your main goal.

Are transactional APIs only for transactional messages?

Yes. You can do some occasional bulk mailing if it is compliant with the terms and conditions accepted by your recipients, but this should be a rare exception.

Which methods should be used for bulk and promotional messages?

Instead of using Transactional APIs, it is recommended you use the specific methods for sending email/SMS campaigns (see docs). For your marketing campaigns we recommend you do a bulk mailing in one of the following ways:

directly from the MailUp web application,
using the bulk REST API 1.1
building your integration based on file transfer and MailUp FTP-ZIP.

Which channels are supported by the transactional APIs?

Email and SMS

Is there a single method that lets me choose the delivery channel (email/SMS)?

No, each channel has its own endpoint and request format.

Are there any sending limitations?

Email: 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 have purchased (e.g. 5,000 messages per hour). See MailUp pricing for more.

SMS: sending is based on credits. Requests fail if there is not enough credit left

Which is the best solution for transactional emails? 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 an 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.
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

Do transactional APIs replace some SOAP methods?

Yes, the transactional API fully cover the feature set of the methods listed below. In addition, the transactional API have to be preferred to the methods they replace, either because of their better performance of because SOAP API could be deprecated soon.

Channel

Replaced SOAP methods

Email

SendSingleNewsletter

SMS

SendSingleSms

SendDirectSMS

What kind of setup is required?

Some preliminary tasks have to be performed the very first time to setup a transactional channel.

Email: you have to create a SMTP+ user to be referenced when invoking the mailing methods. SMTP+ users can be created through the MailUp web application or using the REST API. In both cases, first you have to authorize a trusted sender, then you can create a new user and get its credentials. Please refer to #Link1 and #link2 for the REST API methods. Once you have an enabled user, you can start sending transactional emails.

SMS: an additional API key (aka "ListSecret") has to be generated through a specific API for each MailUp list to be enabled for transactional SMS. Please refer to link#3 to learn how to set and get this key. Once you have the API key value, you can start sending transactional SMS.

Which methods have to be used for sending transactional messages?

Channel	Methods	Reference	Returned values
Email	POST https://send.mailup.com/API/v2.0/messages/sendmessage POST https://send.mailup.com/API/v2.0/messages/sendtemplate	Transactional Emails using APIs	Error codes
SMS	POST https://sendsms.mailup.com/api/v2.0/sms/{account_ID}/{List_ID}	Transactional SMS using APIs	Delivery ID

Which are the main request parameters?

Here is a short list. Please refer to the API documentation for all the details.

Main request parameters

Main options

Advanced options

Email

Recipient's address,
subject,
email body

scheduled datetime,
campaign code*
merge tags (dynamic fields)
Template ID
From
Cc and Bcc
ReplyTo
Charset
Custom headers
Attachments (max 10 MB)
Embedded images
...

SMS

Recipient's number,
SMS text

scheduled datetime,
campaign code*
merge tags (dynamic fields)
Template ID
Sender
...

*the campaign code is an ID that MailUp uses to group the mailing results by the specified ID.

For each new ID, MailUp creates a "message" object, which will act as result container

How does the authentication process work?

Depending on the invoked method, different authentication types are required.

Channel	Operation	Authentication type
Email	Setup	OAuth 2
Email	Send message	SMTP+ credentials in the request body
SMS	Setup	Basic Authentication
SMS	Send message	API key

Is HTTPS supported?

Yes, all the methods can be invoked using only HTTPS (port 443)

How can I manage high priority mailings?

Email: There could be cases in which, due to the purchased frequency and to a FIFO (first-in, first-out) approach, some urgent messages could be delayed by other outgoing messages, like large campaigns that are already in progress. In this cases you need to set a different priority for delivery. Please note that the “priority” value that can be set through the user interface for each SMTP+ user could be misleading. It is just an additional information that some email clients use when displaying the message summary. This setting cannot be used by MailUp to move forward or behind the messages within a delivery queue. If you have mailings with different priorities in terms of delivery (e.g. password reminders have to be very quick, while standard notifications could take longer) you may need a special configuration (aka “fast”) to be set to one or more of your SMTP+ users. Messages sent through the “fast” SMTP+ user use a separate queue. If you send only really urgent messages through this second queue the delivery is likely to be extremely fast. The “fast” configuration is a custom setting, not related to the “priority” value described above. Please contact your MailUp representative to check if it is applicable to your account and if there is an additional cost.

SMS: Unlike the email channel, there is not a guaranteed minimum speed for SMS, which are delivered as fast as possible. All the messages are sent according to the FIFO policy. If all the SMS you are sending through your MailUp account are transactional and you are not happy with the current delivery speed you may contact MailUp support and ask a quote for the special route that is reserved for OTP traffic.

What kind of results I can get from sent messages?

Channel

Result Types

Sample code

Email

Sent
Bounced
Marked as spam
Unsubscribed by clicking the “unsubscribe” link
Opened
Clicked

Click here to expand...

Let’s say we have just sent a transactional email using MailUp list n.3 to peter@example.com, also specifying the CampaignCode “test01”. The value of the CampaignCode is stored in the Subject when you don’t specify the “CampaignName” value

Statistics by recipient

-- Get the recipient’s ID
GET /Console/List/3/Recipients/Subscribed?filterby="Email.Contains(‘peter@example.com’)"

-- Let’s suppose the method above returns "idRecipient":13, then I can get the available outcomes for that recipient (sent, open, click, bounce). 
-- In the example below there is also an additional filter on the sent message
GET /Recipient/13/List/Deliveries?filterby="Subject.Contains(‘test01’)"
GET /Recipient/13/List/Views?filterby="Subject.Contains(‘test01’)"
GET /Recipient/13/List/Clicks?filterby="Subject.Contains(‘test01’)"
GET /Recipient/13/List/BounceDetails?filterby="Subject.Contains(‘test01’)"

Statistics by message

-- Get message’s ID
GET /Console/List/3/Emails?filterby="Subject.Contains(‘test01’)"&orderby="idMessage+asc"

-- If the method above returns "idMessage":27, then I can use this value to get the outcomes, either the aggregate counts or the detailed list. 
-- Detailed lists can also be filtered, see the documentation for details
GET /Message/27/Count/Recipients
GET /Message/27/Count/Views
GET /Message/27/Count/Clicks
GET /Message/27/Count/Bounces
GET /Message/27/List/Recipients
GET /Message/27/List/Views
GET /Message/27/List/Clicks
GET /Message/27/List/Bounces

SMS

Sent to the carrier (pending)
Delivered
Failed

Statistics by recipient

When you successfully send an SMS using the transactional APIs, a Delivery ID is returned

{"Data":{"DeliveryId":1648,"Cost":1.0},"Code":"0","Description":"","State":"DONE"}

Then you can use this ID to query MailUp REST API about the delivery status

GET /Console/Sms/{SMS_ID}/Sendings/ReportDetails?DeliveryId=1648

Statistics by message

For example, you sent transactional SMS keeping the same campaing code 'Promo 1' in the parameters. Then you can query MailUp REST API about the delivery status of the SMS sent with this campaign code

-- First get the message ID that was created for 'Promo 1'
GET /Console/Sms/List/1/Messages?filterby="Subject.Contains('Promo 1')"
 
-- Let's say that the previous call returns 24 as message ID
-- Then you can call one of the following methods to get the delivery results
-- You can also apply filters using querystring parameters (refer to the documentation)
GET /Console/Sms/24/Sendings/Report
GET /Console/Sms/24/Sendings/ReportDetails