Page tree

Versions Compared


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


  • 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

What kind of setup is required?

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


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.

ChannelReplaced SOAP methods




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.


ChannelResult TypesSample code
  • 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, 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(‘’)"

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



  • Sent to the carrier (pending)
  • Delivered
  • Failed
titleStatistics by recipient

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

Code Block

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




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.


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.



Applies to


SMTP+ settings

SMTP+ only

Host name = (also is supported)

Allowed ports = 25, 80, 1025-5000

Security = None or Start TLS

API settings

API only

Base host name =

Allowed ports = 443

Security = HTTPS


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



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, 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(‘’)"


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



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





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





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