...

...

...

...

What kind of setup is required?

...

...

...

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

...

POST https://sendsms.mailup.com/api/v2.0/sms/{account_ID}/{List_ID}

...

*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

Is sample code available? 

Work in progress

• https://www.snip2code.com/Snippet/498949/MailUp-REST-API---How-to-send-a-transact

How does the auhtentication process work?

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

Is HTTPS supported? 

...

...

...

...

What kind of results can I get from sent messages? 

Status
colour Yellow title DRAFT

...

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

...

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

...

...

-- 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’)"

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

...

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

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

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

...

...

How to send transactional emails

There are two ways of sending transactional emails using MailUp:

1. Using the SMTP relay, also called MailUp SMTP+ (link). The SMTP+ service, now available in v2 for all MailUp customers, provides a powerful and reliable service, you just have to create an SMTP user on MailUp, and then you can use it on your client application, just like when you are connecting to any SMTP server. There is no limit on how much you can send, but your speed limit is based on the purchased frequency. In addition, you can also specify a “campaign code” in order to let MailUp aggregate outcomes with the same code (this can be very useful for reporting purposes).
2. Using the MailUp transactional API (link), which shares has the same behavior of MailUp SMTP+, the only differences are the interface towards the client and an additional option that allows the API clients to provide a message ID instead of passing the whole message body. Even the performances are the same; you simply have to choose the solution that better suits your client application.

MailUp customers who are willing to use API to retrieve statistics are likely to choose solution 2, while those who use FTP based integrations to get the outcomes usually prefer the first solution. We will cover how to obtain statistics later, in the next chapter.

The two sending methods listed above are the recommended choices for sending transactional emails, while you should avoid

• All the methods of MailUp SOAP API, which may become deprecated soon
• The sending methods that belong to the “standard resources” of REST API 1.1, which are designed to work well with bulk mailing (e.g. marketing campaigns) and resource management, but they are not the right choice for transactional emails

In the MailUp documentation, all about the transactional API is marked with version 2.0, while the latest version of the other REST API is 1.1. Don’t be afraid if you see different versions, they are fully compatible.

Authentication

Both the available methods for transactional emails require to create first an SMTP+ user. This operation is usually done at setup time through the MailUp web interface (link). A pop-up form will show you the access credentials, that you must keep in a safe place.

In addition to the web application, you may also use specific API methods to create a new SMTP+ user (link). Please note that these methods require a different authentication type: use them only if your application needs to create new users programmatically.

There is no limit on the number of users you can create for a specific MailUp account. As better explained in the next chapter, you may need more users to have different aggregations (for statistics) or different priority levels.

Once you have your SMTP+ user, you can start testing by sending a request:

• Check out here for a sample PHP code using MailUp SMTP+.
• Refer to the documentation of the MailUp transactional API (link) to know more about the request parameters and the response values

Returned responses

Both SMTP+ and the MailUp transactional API are fully asynchronous. You can only know if your request has been accepted by the server on the other end.

With SMTP+, a standard SMTP code is returned, while for API you can use this page as a reference.

SMTP reference

Can I also do some occasional bulk mailing using the transactional solutions?

Yes, you can, if it is compliant with the terms and conditions accepted by your recipients, but this should be a rare exception. 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.

How can I manage high priority mailings?

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.

Please note that the “priority” value that can be set for each SMTP+ user 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.

You can access to outcomes with one or more of the following ways

• MailUp REST API using a “cron” (time based)
• MailUp REST API using a “refresh” direct call from your application (on demand)
• Batch export (periodic update, max once a hour, best choice with very large amount of data)
• Webhooks (with many restrictions, not recommended)
• Public pages to embed a page with statistics in your application (with restrictions)

The following paragraphs provide some details about the solutions listed above

REST API 1.1

The use of API is an excellent choice when you want to synchronize your system with MailUp by means of a simple set of API calls: you have full control on when the synchronization has to occur. In case of big amounts of returned data you can use the “paging and filtering” options provided by the API.

At MailUp we believe that REST API is the best choice when compared to the other choices we provide. Technically speaking, you can either set up a “cron” for an automatic update or an “on-demand” call to refresh the data on your CRM with the latest update.

These are some examples about how to retrieve statistics using REST API (click here to access the full documentation).

Batch export

MailUp can set up for you a personalized export batch, based on “standard full export” but easily customizable, that can return the data you need to update your system. This batch can run hourly, daily or even weekly and provides a CSV that is made available using FTP. Export batches can support very large files, hence they are a good solution if a periodic update fully fits your needs. Please refer to the documentation of FTP-based data export (link).

Webhooks

As stated in the previous chapter, MailUp supports webhooks only for some single opt-in and opt-out operations. Here below is explained why MailUp is not going to extensively support webhooks and continues to prefer synchronization flows that are led by the client MailUp is connected to:

Even though some other ESPs provide webhooks related to any mailing events, it is likely that none of them is able to guarantee a response time, especially when mailing volumes scale up or you have bursts of events during the day.

In addition, what happens if your system is down and becomes unable to process callback functions? Yes the ESP retries several times, but if your downtime is longer, how do you manage to re-synchronize?

In our experience, clicks opens and even bounces often come with bursts, a very big number of events in a very short time, if the client application connected to MailUp is not robust enough, some data may be lost when a peak occur. We prefer to let the client application be the “master”, who decided when and how often ask to MailUp if there are any updates.

Public pages

MailUp provides a few web pages that can be called by a CRM, or even be embedded into it. Since it is a small set of pages, this is just a partial solution that can be used together with one or more of the previous ones.

Readers report

By calling an URL composed of ListGuid and MessageId you can get opens and clicks

http://{accounthostname}/frontend/user_views_report.aspx?listGuid={list_GUID}&idList={list_ID}&idnl={message_ID}

Figure 1: Readers report

Bounces report

By calling an URL composed of ListGuid you can a paged list of the returned bounces (sorted by the most recent first)

This page can be reached by calling this URL

http://{accounthostname}/frontend/bounce_log.aspx?listGuid={list_GUID}&idList={list_ID}

Figure 2: bounces

General best practices about handling recipients

This section contains some general rules that are about how to properly handle recipients in MailUp. It also covers topics that go beyond the basics of what you have to do with transactional emails.

• If you send a transactional email to an email address you have never used before on MailUp, the recipient will be automatically subscribed (single opt-in).
• If the recipient is already present as “unsubscribed” or “pending” (i.e. not confirmed yet), the message will not be sent
• Subscription occurs at MailUp list level (e.g you may be unsubscribed from list 1 “promotions”and remain subscribed to list 2 “announcements”)
• The most important recommendation is “send only to verified addresses”. You can’t keep a good reputation if you don’t take care of your database. Whenever you add a new email address to your database, you should send a confirmation request to it before you start sending transactional (or other) emails. To do this, you can implement your own verification system or, even better, you can use MailUp to do this. The paragraph below explains how to implement the “confirmed Optin” (COI) flow using MailUp.

How to implement COI with MailUp

Here is how COI works on MailUp:

1. The specified recipient is imported as “pending”
2. A confirmation request is sent to the pending recipient using an email template that you can customize on MailUp platform. This email contains the “subscription link” to be clicked in order to confirm your subscription.
3. The recipient cannot receive other emails until it is in pending status
4. When the recipient clicks on the “subscription link”, it is automatically added to the list of “subscribers”, who are enabled to receive the messages from the MailUp list he/she is subscribed to

The higher is the number of the emails you have sent with wrong or invalid addresses and the lower is your reputation. Since confirmation requests using MailUp are sent on a different route, your reputation is only slightly affected in case of wrong addresses during the COI process.

How to handle unsubscriptions

Unsubscription (opt-out) may occur in one of the following ways

• MailUp administrator forces opt-out through the MailUp web application
• A recipient unsubscribes by clicking the “Unsubscribe” link of a received message
• A recipient marks an email as spam using its email client. When applicable[1], MailUp is notified of this event and immediately forces opt-out
• A mailing returned a hard bounce because the specified email address is not valid. For the sake of your account reputation, MailUp forces opt-out in case of repeated hard bounces.

Automatic notifications related to opt-in and opt-out

You can configure callback functions (webhooks) when a single recipient opted-out by clicking the “unsubscribe” link or when a new address is added (opt-in) through a MailUp form. Other types of opt-in or opt-out are not handled by webhooks.

In addition, you may ask for a personalized periodic data-synch, in which a custom data set is exported and made available by means of a csv file tran

...