Page tree

Versions Compared


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


Table of Contents

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

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 by these APIs?

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:


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


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?


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:


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.


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