Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

 

How can I manage high priority mailings?

...

colourYellow
titleDRAFT

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 your account and if there is an additional cost.

SMS: aaa

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 can I get from sent messages? 

...

...

 

ChannelResult TypesSample code
Email
  • Sent
  • Bounced
  • Marked as spam
  • Unsubscribed by clicking the “unsubscribe” link
  • Opened
  • Clicked
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

Code Block
titleStatistics 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’)"
Code Block
titleStatistics 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
Expand
titleStatistics by recipient

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

Code Block
{"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

Code Block
GET /Console/Sms/{SMS_ID}/Sendings/ReportDetails?DeliveryId=1648
Expand
titleStatistics 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

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

 

 

...

Expand

 

How to send transactional emails

There are two ways of sending transactional emails using MailUp:

  1. Using the SMTP relay, also

...

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

...

  1. the MailUp transactional API (link), which shares has the same behavior of MailUp SMTP+, the only differences are the interface towards the client and

...

  1. an additional option

...

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

With both the methods you can specify

...

the X-SmtpAPI

...

 parameter for an advanced setup. This parameter is composed of several optional fields, and the most important are:
- CampaignCode = external identifier specified by the customer. It is used to aggregate messages with the same code and then to provide meaningful statistics
- Schedule = sending date and time, to be used in case of deferred sending
- Dynamic fields = key-value pairs, to be used when you want to personalize a message starting from a template containing placeholders

X-SMTP

...

 API is provided as a special header with MailUp SMTP+, while it is an optional parameter of MailUp transactional API. Please refer to the technical documentation for details.

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.

 

Parameter

Applies to

Value

SMTP+ settings

SMTP+ only

Host name = fast.smtpok.com (also in.smtpok.com is supported)

Allowed ports = 25, 80, 1025-5000

Security = None or Start TLS

API settings

API only

Base host name = https://send.mailup.com/API/v2.0/messages/

Allowed ports = 443

Security = HTTPS

Credentials

Both SMTP+ and API

Username = s + your MailUp ID + _ + a progressive number (e.g. s13231_1)

Password = Automatically generated and shown only at creation time, later you can only reset it

 

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

...

...

  •  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

...

...

 

 

 

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

 

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

 

 

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

 

Any of the following methods can be used to add a subscriber using COI:

1) Use HTTP Post method (link to docs)

GET http://{accountdomain}/frontend/xmlsubscribe.aspx?email=name@sample.com&List={lists}&Group={groups}

2)Use REST API to add a single subscriber (link to docs), confirmation message is automatically sent

POST /Console/List/{id_List}/Recipient?ConfirmEmail=true

3) Use REST API to add a Use REST API to add a Use REST API to add a list of subscribers (link to docs) and send a bulk confirmation message (requires more calls)

POST /Console/List/{id_List}/Recipients?ConfirmEmail=true  //Prepare bulk mailing

GET /Console/Email/Sendings/Immediate //get mailing ID

POST /Console/Email/Sendings/{mailing_id}/Immediate //send

4) Use subscription forms provided by 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.

MailUp denies any attempt to send messages to unsubscribed (or pending) recipients.

In some cases MailUp web application lets you force re-subscription of recipients (e.g. someone who unsubscribed by mistake or returns to be interested in your mailings), but it is strongly recommended that you contact us before doing this the first time, so that MailUp deliverability department can assist you with some best practices.

 

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

...

 As a certified ESP, MailUp receives notifications (aka “feedback loop”) from many ISPs, including Gmail, Hotmail, Yahoo!

 

...