Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

RESTRICTED ACCESS

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.

What should be used for bulk and promotional messages?

In this case it is recommended you use the specific methods for sending email/SMS campaigns (see docs). 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. For your marketing campaigns we recommend you do a bulk mailing in one of the following ways:

Which channels are supported?

Email and SMS

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

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

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

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?


ChannelMethodsReferenceMain request parametersOptional request parametersReturned values
Email  Recipient's address, subject, email bodyscheduled datetime, campaign code*, ... 
SMS  Recipient's number, SMS textscheduled datetime, campaign code*, ... 

Is sample code available?

boh

How does the auhtentication process work?

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

ChannelOperationAuthentication type
EmailSetupOAuth 2 
EmailSend messageSMTP+ credentials in the request body
SMSSetup Basic Authentication 
SMSSend messageAPI key

 

Is HTTPS supported?

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

 

How can I manage high priority mailings?

(email only)

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.

 

What kind of results can I get from sent messages?

With the word “outcomes” we mean each one of these results related to an email:

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

 


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.

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

 

 

 

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



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

  • No labels