MailUp API
Page tree

Versions Compared

Old Version 20

changes.mady.by.user MailUp Dev Team

Saved on

compared with

New Version Current

changes.mady.by.user Alessandro Tegagni

Saved on

Key

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

...

Info

This page contains many collapsed sections that contain details about recommended methods in SOAP, REST, HTTP GET/POST API. Use the "Click to expand" links to reach hidden parts.

 


On this page:

Table of Contents
maxLevel4
 


...

Manage single recipients (subscribe, unsubscribe, update)

MailUp provides several ways to add a new subscriber and manage either data fields or subscription status. If you’re in the process of developing a generic application interacting with multiple accounts, it must be considered that personal data fields may differ from account to account.

We recommend to always make making use of the “retrieve field names” feature, returning the actual field names and Id occurences occurrences for a particular admin console account. Those returned occurrences can be used to update personal data recipient fields afterwards. afterward.


Expand
titleClick here to expand and see available solutions and recommended methods
HTTP GET/POST and subscription forms

Subscription forms are based on HTTP GET/POST methods, which allow subscription unsubscription, check subscription status and update for a single recipient. These methods support optin, confirmed optin, optout, fields update, unsubscription. Refer to this page if you want to build a custom subscription form using AJAX. Retrieve The retrieve fields feature is not available with HTTP GET/POST.

Expand
titleClick here to expand for recommended methods


Action

Comments

Get/Post API

Confirm successful communication with the APIThis
refers to confirming that the API credentials entered by the user are correct. The method used should return useful errors so that the user is informed of what might be going wrong
method may be useful if your application needs to ping mailup to check current authentication and connection statuses.WSActivation.aspx

Activation

You can enable HTTP GET/POST calls for any caller, you can restrict usage to a set of IPs or you can call a method that registers the caller IP

in order

to add it to the list of authorized IPs.

WSActivation.aspx

Single Subscribe (client-side)

Subscribing

Subscribes a single recipient to one or more lists (e.g. during checkout or registration) by calling a page that redirects to a landing page displaying the result

Subscribe.aspx

Single Subscribe (server side1)
Subscribing
Subscribes a single recipient to one or more lists (e.g. during checkout or registration) and
returning
returns a result to the callerXmlsubscribe.aspx

Single Unsubscribe (server side1)

Unsubscribing

Unsubscribes a single recipient from one or more lists (e.g. customer updates their account in the storefront) and returning a result

XmlUnsubscribe.aspx

Single Update (server side1)

Updating

Updates a single recipient based on mapped data fields (e.g. first name, last name, etc) and

returning

return a result

XmlUpdSubscriber.aspx

Retrieve subscription status for a specific customer and list (server side1)

This refers to determining whether a certain recipient is subscribed to a given list or not, so that the correct subscription preference can be shown in your application (or to update locally stored subscription preferences).

Retrieves recipient’s status ( subscribed, pending, or unsubscribed )

XmlChkSubscriber.aspx

(1) requires server-side development, and in the case of AJAX implementations, this operation cannot be done directly from a client page because cross-domain requests are blocked by the "same-origin policy"

REST API

Rest API is the most complete solution for managing a single subscriber ( handles subscription status, group membership, and personal data fields) and . In addition, it is the only MailUp solution that allows the removal of a single recipient from a group. Adding a new recipient is an asynchronous process (i.e. the method's response does not mean that the operation is completed, you could use a specific method to get the status of the requested operation). Retreive Retrieve fields feature is available with GET /Console/Recipient/DynamicFields 

Although the MailUp REST API is the most complete solution for managing a single subscriber, please keep in mind that it is subject to rate limiting, so some calls could be blocked if you are exceeding the allowed number of calls/s. For this reason, if your source is a web form with high subscription traffic you would be better off considering the HTTP GET/POST for new subscriptions.


Expand
titleClick here to expand for recommended methods


Action

Comments

REST API

Confirm successful communication with the API

This refers to confirming that the API credentials entered by the user are correct. The method used should return useful errors so that the user is informed of what might be going wrong.GET
Returns authentication information.


GET /Console/Authentication/Info

Retrieve Lists

This refers to storing the information needed to then enable/disable Lists to be shown to users of the application so that they may subscribe/unsubscribe to/from different Lists

Retrieves all lists related information

GET /Console/User/Lists

Retrieve Groups
This refers to storing the information needed to pass a Group ID when sending data back to MailUp (e.g. to assign subscribers to a certain group)

Retrieves groups for a certain list

GET /Console/List/{ID_LIST}/Groups

Retrieve Fields

This refers to storing field ID and field name to allow for mapping between fields in the MailUp account and those in the integrated application

Retrieves the actual personal data field names along with ids. Useful for adding or updating subscribers’ personal information afterward.

GET /Console/Recipient/DynamicFields

Single Subscribe

Subscribing

Subscribes a single recipient to one

or more lists (

list (e.g. during checkout or registration). A confirmed optin process can be implemented using the ConfirmEmail parameter

POST

/

Console/List/{

id_List

ListID}/

Subscribe/{id_Recipient}

Recipient (without COI)

POST Console/List/{ListID}/Recipient?ConfirmEmail=true (with COI)

Single Unsubscribe

Unsubscribing

Unsubscribes a single recipient from one or more lists (e.g. customer updates their account in the storefront)

DELETE /Console/List/{id_List}/Subscribe/{id_Recipient}

Single Update

Updating GET /Console/List/

Updates a single recipient based on mapped data fields (e.g. first name, last name, etc)

PUT /Console/Recipient/Detail

Retrieve subscription status for a specific customer and list

This refers to determining whether a certain recipient is subscribed to a given list or not, so that the correct subscription preference can be shown in your application (or to update locally stored subscription preferences).

Returns all subscribed recipients to a certain list

GET /Console/List/{id_List}/Recipients/Subscribed?filterby="Email.Contains('{Email}')"


Webhooks

You can configure webhooks to enable a fast callback to your website everytime every time a recipient changes the subscription status or any of the personal data fields (e.g. by filling in and submitting to an autoprofile auto profile form). Callback The callback method can be configured in order to include the recipient's details as the method parameter. Webhooks are managed by a worker process that is like a "frequent cron": you may experience some minutes of delay between the action and the corresponding callback. Bounces cannot be notified through webhooks.

SOAP API

You can extend the use of StartImportProcess method of MailUpImport SOAP API, that is designed for bulk import, to work with a single recipient. This method allows optin, confirmed optin, forced optin, optout, fields update, unsubscription. Adding or updating a recipient with SOAP API is an asynchronous process (i.e. method response does not mean that the operation is completed, you could use a specific method to get the status of requested operation). Method MailUpSend.GetFields can be used to retreive field names.

Expand
titleClick here to expand for recommended methods

Action

Comments

SOAP Web Services

Confirm successful communication with the API

This refers to confirming that the API credentials entered by the user are correct. The method used should return useful errors so that the user is informed of what might be going wrong.

MailUpSend.LoginFromId

Retrieve Lists

This refers to storing the information needed to then enable/disable Lists to be shown to users of the application so that they may subscribe/unsubscribe to/from different Lists

MailUpImport.GetNlLists

Retrieve GroupsThis refers to storing the information needed to pass a Group ID when sending data back to MailUp (e.g. to assign subscribers to a certain group)

MailUpImport.GetNlLists or

WS_MailUpSend.GetGroups

Retrieve Fields

This refers to storing field ID and field name to allow for mapping between fields in the MailUp account and those in the integrated application.

MailUpSend.GetFields

Single Subscribe

Subscribing a single recipient to one or more lists (e.g. during checkout or registration)

MailUpImport.StartImportProcesses

Single Unsubscribe

Unsubscribing a single recipient from one or more lists (e.g. customer updates their account in the storefront)

MailUpImport.StartImportProcesses

Single Update

Updating a single recipient based on mapped data fields (e.g. first name, last name, etc)

MailUpImport.StartImportProcesses

Retrieve subscription status for a specific recipient/list

This refers to determining whether a certain recipient is subscribed to a given list or not, so that the correct subscription preference can be shown in your application (or to update locally stored subscription preferences).

N/A

Synchronize recipients between your application and MailUp (i.e. bulk import and/or export)

You may need to transfer a set of recipients, possibly with their personal data, from your application to MailUp; or viceversa. Solutions that work well with a single recipient may not be suitable for big amounts of recipients, in this case bulk solutions are required.

When plannin a synchronization approach you must take care about how unsubscription is made. In particular, you should be aware that, when importing subscribers that are already present and unsubscribed in specified MailUp list, unsubscription status is not changed, except for the cases in which you deliberately set an API option that forces subscription.

  • If unsubscription is natively managed by MailUp via the "Unsubscribe" link normally nested in the email footer, forcing subscription should be considered only when an unsubscribed recipient specificly asks to be subscribed again
  • If unsubscription is managed by an external system outside MailUp (i.e the "Unsubscribe" link in email footer leads to an external site) then the external application runs as "master" database and you should consider to force subscription whenever you import recipients.

Several possible solutions are available

Expand
titleClick here to expand and see available solutions and recommended methods
FTP based integrations

You can request your MailUp representative for a FTP Batch Process for massive data transfer using files CSV files. This feature can be used for very large amounts of recipients (this kind of process has been successfully tested with 4 millions of recipients in a single file).

Expand
titleClick here to know more about available FTP transfer types

You can request this feature to

Data transmission does not take place in real time: it is usually configured on a daily or weekly basis, but for specific cases even hourly schedule can be considered )

FTP based integrations can also be customized to import external campaign codes ( meant as customer’s application internal campaign or recipient identities )   without using personal data fields and to export email statistics with their reference to the external campaign code. This feature is not available with MailUp web services. More on this.

SOAP API

You can run MailUpImport SOAP API for an immediate import of recipients. In particular, you can use StartImportProcesses method, optionally combined with NewImportProcess if the amount of recipient is more than 5000. These methods also allow a batch import as "pending", and in this case, the confirmation email has to be manually sent using the admin console account. SOAP API is not bidirectional, so you cannot use it to export recipients from MailUp to your application.

Expand
titleClick here to expand for recommended methods

Action

Comments

SOAP Web Services

Confirm successful communication with the API

This refers to confirming that the API credentials entered by the user are correct. The method used should return useful errors so that the user is informed of what might be going wrong.

MailUpSend.LoginFromId

Retrieve Lists

This refers to storing the information needed to then enable/disable Lists to be shown to users of the application so that they may subscribe/unsubscribe to/from different Lists

MailUpImport.GetNlLists

Retrieve GroupsThis refers to storing the information needed to pass a Group ID when sending data back to MailUp (e.g. to assign subscribers to a certain group)

MailUpImport.GetNlLists or

WS_MailUpSend.GetGroups

Retrieve Fields

This refers to storing field ID and field name to allow for mapping between fields in the MailUp account and those in the integrated application.

MailUpSend.GetFields

Bulk Subscribe

Subscribing a set of recipients to a list

MailUpImport.StartImportProcesses

Bulk Unsubscribe

Unsubscribing a set of recipients from a list

MailUpImport.StartImportProcesses

Bulk Update

Updating personal data fields of a set of recipients

MailUpImport.StartImportProcesses

Retrieve list of subscribers

Retrieving recipients that are subscribed to a list

N/A

SOAP API + FTP

You can get the best of FTP and SOAP API by using SendMessageNL API method, which performs scheduled sending of a message to a set of recipients that are included in the FTP import file previously processed (message ID and filename are passed as method parameter). In this case you have to transfer the file to MailUp before calling the method. Export of subscribed and unsubscribed recipients can be done with an FTP based integration.

REST API

Rest API allows immediate and bidirectional import and export of recipients. Due to restriction on HTTP channel, no more than 7MB input files can be uploaded with a single import. For the export of recipients the paging feature is recommended to keep control on maximum size of transferred data. REST API is the only MailUp solution that allows removal of a single recipient from a group.

Expand
titleClick here to expand for recommended methods

Action

Comments

SOAP Web Services

Confirm successful communication with the API

This refers to confirming that the API credentials entered by the user are correct. The method used should return useful errors so that the user is informed of what might be going wrong.

GET /Console/Authentication/Info

Retrieve Lists

This refers to storing the information needed to then enable/disable Lists to be shown to users of the application so that they may subscribe/unsubscribe to/from different Lists

GET /Console/User/Lists

Retrieve GroupsThis refers to storing the information needed to pass a Group ID when sending data back to MailUp (e.g. to assign subscribers to a certain group)

GET /Console/List/{ID_LIST}/Groups

Retrieve Fields

This refers to storing field ID and field name to allow for mapping between fields in the MailUp account and those in the integrated application.

GET /Console/Recipient/DynamicFields

Bulk Subscribe

Subscribing a set of recipients to a list

 POST /Console/List/{id_List}/Recipients or POST /Console/Group/{ID_GROUP}/Recipients

Bulk Unsubscribe

Unsubscribing a set of recipients from a list

N/A

Bulk Update

Updating personal data fields of a set of recipients

POST /Console/List/{id_List}/Recipients or POST /Console/Group/{ID_GROUP}/Recipients

Retrieve list of subscribers

Retrieving recipients that are subscribed to a list

GET /Console/List/{ID_LIST}/Recipients/Subscribed

Manage suppression lists (i.e. "do not email" lists of recipients)

Suppression lists are not natively supported by MailUp but you can create a dedicated group of recipients to  exclude from sending. In order to automate the process, you can contact MailUp support department and request for the configuration of an FTP based integration with a batch process runing hourly. This process has to be set to import in a new group ( where the destination group name mathces the actual import file name) the recipents that are listed in the file to be imported. Then, when you access to MailUp admin console, you can schedule  or fire your campaign to be sent to "all subscribers except for the recipients that belong to a certain group". It should be easy for you to identify the right group because it has the name of the imported file plus a timestamp.

 

 Send transactional and other personalized emails

 Sending messages through MailUp from an external application allows you to take advantage of:

  • The high reputation and scalability of the MailUp sending infrastructure
  • Automatic bounce and feedback loop management
  • Ability to include dynamic tags and dynamic content
  • Ability to check the send status via API

 

The use of dynamic fields (or dynamic tags) allows you to send individual email messages containing some personalized content. These messages - often transactional emails - typically consist of a template plus some personalized fields: for example, a password reminder, a form submission confirmation, an order confirmation, and so on. MailUp can manage the whole process automatically:
  • Messages are sent out very quickly, due to a robust and scalable infrastructure that guarantees immediate sending (except in case of grey listing on destination servers). 
  • There are no bandwidth restrictions and a dedicated channel is used for sending these messages (no queue-related delay). 
  • Automated processes can be activated following actions (subscribe, open, click or personal field update ) that recipients might have performed.
  • NOTE: this channel cannot be used to send bulk email messages, but rather only for transactional emails. There are limitations in place that prevent system abuse (see API use policy).
Expand
titleClick here to expand and learn how you can send transactional messages using MailUp

MailUp can send transactional emails in three ways. Depending on the speed and on the amount of messages to be sent, you can stick to the single option or, even better, you can mix them to get the best result.

By using the method used to send confirmation messages

MailUp sends a confirmation message to subscribers through an automatic procedure. Subscription can take place in two ways:

The content of the subscription confirmation message can be modified, so to make it correspond to the template of the message you want to send (only one confirmation message can be set for each list, but you can set up multiple lists within your MailUp account).

The confirmation message can be personalized with the recipient's personal data by using dynamic fields (up to 40 available when purchasing the Marketing+ package).

These confirmation messages can also contain a link triggering subsequent actions (opening of a messages page and automatic sending of another email), through the use of SUB link. A specific list can be created for the purpose, and each list can have a different sender address. 

By using Web services

A web service allows the immediate sending of a single message. This procedure is much more flexible than the previous one, but it is recommended to strictly follow the instructions provided in the section describing this function.

The WS_MailUpSend.SendSingleNewsletter allows to send an email message with the indication of subject, recipients and contents. Dynamic fields (i.e. placeholders that are replaced with recipient's personal data values before sending) are supported, while dynamic content is not supported.

This is the best choice for transactional messages that have to be delivered in few seconds (e.g. password reminder, account credentials after signup), however this solution has some limitations (see API use policy and the box below). In many cases you can have a good trade-off by using either web services and SMTP relay service.

Note
When using SendSingleNewsletter(), the best practice is to use predefined messages with dynamic sections, and not to create a brand new newsletter for each call. In this case MailUp would keep on using space to store the new content, which can negatively affect performance for your MailUp account. If you are in need to send hundreds (or more) of fully personalized transactional messages and you cannot use a predefined message, please contact us. 
By using SMTP relay service

With SMTP+ feature, your application can take advantage of a high deliverability SMTP server provided by MailUp. No need of integration with MailUp API, all you need is a set of SMTP credentials. SMTP+ offers a scalable solution that is valid also for high volumes of transactional email messages to be sent. There is a couple of things to know: delivery time depends on the bandwidth agreed for that console account and dynamic fields are not supported. This is the best choice for big amounts of personalized messages that do not have to be delivered in few seconds.

 

Bulk email messages

This section describes the different ways through which MailUp can be used to send email messages to groups and lists of users without accessing the administration console. The methods described above can be used to send individual, personalized messages, such as transactional emails. However, if the goal is to send large amounts of messages or DEMs, the best practice to follow is described below.

Some possible scenarios are presented here - with the indication of the web services to be used - as examples of common scenarios. This is in no way an exhaustive overview of all the possible scenarios. 

Please note that these cases do not talk about authentication and authorization, you should refer to the specific documentation of each technical solutions for these details.

 

Expand
titleCase 1: email message and recipients exist in the MailUp admin console (click here to expand)

You may want to send a message to a group of users and both the message and the recipients list are already available in the MailUp console.

SOAP API
  1. If the message has to be sent to all the recipients in a list the suggested method is WS_MailUpSend.SendNewsletter. Parameters "send_to = ALL" , list ID, message ID and time and date of sending must be specified. Message and list IDs can be found at the page Settings > Codes Tables  in the MailUp console, or using GetLists() and GetNewsletters() methods.
  2. If the recipients belong to some groups in a list, when calling the SendNewsletter() method the group IDs must be specified as well.
  3. If the users share data that can be extracted using one of the MailUp filters (personal data, activity and geolocation filters, available in the Marketing+ package) when calling the SendNewsletter() method the filter to be applied must be indicated as well. Filters can be used in addition or as an alternative to groups. The great advantage of using them lies in the fact that all the recipients matching a certain condition are automatically included in the filter results, whereas a user must be inserted into a group for group membership.

 

Note

It is imperative that you do not use SendSingleNewsletter() in place of SendNewsletter(): the first one has to be used only for transactional emails, as described above. Use of SendSingleNewsletter() for the purpose of sending bulk email messages will trigger a send block on your account and may lead to account termination.

REST API
  1. If the message has to be sent to all the recipients in a list you can call POST /Console/List/{id_List}/Email/{id_Message}/Send.
  2. If the message has to be sent to a group of a MailUp list you can call POST /Console/Group/{id_Group}/Email/{id_Message}/Send

 

Note

Message, group and list IDs can be found at the page Settings > Codes or they can be retrieved using API. Optionally, you can specify also sender name or sender email if you want to use for that message a sender that differs from the default sender of tha MailUp list. At the moment only immediate sending is available with REST API (i.e. you cannot schedule sending). More details are available in the documentation of MailUp REST API

...

titleCase 2: not all recipients exist in the MailUp admin console (click here to expand)

Similar to Case 1, but in this case a group of recipients has to be imported as well. Some of these recipients might be already subscribed in MailUp due to a previous signup to a newsletter, some others might be new subscribers. Here below some alternative solutions are listed, refer to Comparison Matrix to see how many recipients can be loaded with each solution.

SOAP API

...

Note

SendMessageNL is often the best option for a fast bulk import and sending but users should be aware of some known limitations

REST API

REST API supports only sending to a single group or to the whole list

...

LIST+

List+ allows you to enclose a list of recipients to the message to be sent (by using a file named one2many.import) instead of sending to lists or groups that are already present in MailUp. Click here for more information about this feature

...

titleCase 3: creating and sending a message via the MailUp API (click here to expand)

In some cases it may be necessary to import into MailUp a message created using an external system.

SOAP API

The CreateNewsletters() method allows the creation of a new message where the parameter to be passed is the body of the message (html, text or URL that points to the html file).
It is also possible to use the SendNewsletterFast() method, which conveys to a single call the information that can be drawn from the calls to CreateNewsletters() and SendNewsletter() methods.

...

REST API

REST API provides more features than SOAP API about creation and editing of an email message. With REST you can fully handle message tags, images and attachments.

  1. To create a message use POST /Console/List/{id_List}/Email, passing message content as parameter. Check out this page to know more about the available options
  2. Use the methods listed in Case #1 for sending email message with REST API
LIST+

With List+ you can create an email message with your email client or your application and send it to a MailUp specific email address. Depending on the specified address, this action can lead to

  • save email message to MailUp and send it to all the recipients of a MailUp list
  • save email message to MailUp and send it to all the recipients of one or more groups in a MailUp list
  • save email message to MailUp without sending it
  • save email message to MailUp and send it to a recipient for test purposes

This solution is very powerful if you want to work outside the MailUp console account and it has some interesting additional features like automatic upload of images, support for dynamic fields and sender verification. In addition, List+ allows you to enclose a list of recipients (by using a file named one2many.import) instead of sending to existing lists or groups.

SMTP+

With SMTP+ you can create email messages with your email client or your application and send them to the recipients through MailUp. In this case MailUp acts mainly as a high deliverability SMTP server, but it also provides important features like bounce management and statistics. The content of sent message is not saved to MailUp and delivery speed depends on agreed bandwidth for your account.

Expand
titleCase 4: cloning a message to track separate mailings (click here to expand)

Most customers need to track campaign results. When the same message is sent more than once (three different times, to three different groups), statistics are accumulated and pertain to all mailings, not the three individual mailings. To work around, you can make a copy of a message by cloning it before sending. 

SOAP API

You can use the CloneMessage() method

REST API

You can use GET /Console/List/{id_List}/Email/{id_Message} to get message content and then you need to create an identical message with POST /Console/List/{id_List}/Email

Expand
titleCase 5: massive sending of personalized messages via Web Services (click here to expand)

If you are in need to send a high number of personalized messages through the API, please contact us. We can create custom MailUp configurations for you that will address your needs. For example, we worked with a Web site that needed to send hundreds of thousands of personalized alerts on a daily basis, and needed to do so through the MailUp API. 

SOAP API, REST API and List+

You can create personalized sections within your email by means of Dynamic Content feature and MailUp filters. Dynamic Content is not available with email messages sent with HTTP GET/POST API, SendSingleNewsletter (SOAP API) and SMTP+

SMTP+

With SMTP+ you can create email messages with a fully personalized content that varies for each recipient. Using your email client or your application you can send these messages to the recipients through MailUp. In this case MailUp acts mainly as a high deliverability SMTP server, but it also provides important features like bounce management and statistics. The content of sent message is not saved on MailUp and delivery speed depends on agreed bandwidth for your account.

...

Synchronize recipients between your application and MailUp (i.e. bulk import and/or export)

You may need to transfer a set of recipients, possibly with their data, from your application to MailUp; or vice-versa. Solutions that work well with a single recipient may not be suitable for big amounts of recipients, in this case, bulk solutions are required.

When planning a synchronization approach you must take care about how unsubscription is made. In particular, you should be aware that, when importing subscribers that are already present and unsubscribed in a specified MailUp list, unsubscription status is not changed, except for the cases in which you deliberately set an API option that forces subscription.

  • If unsubscription is natively managed by MailUp via the "Unsubscribe" link normally nested in the email footer, forcing subscription should be considered only when an unsubscribed recipient specifically asks to be subscribed again
  • If unsubscription is managed by an external system outside MailUp (i.e the "Unsubscribe" link in the email footer leads to an external site) then the external application runs as a "master" database and you should consider forcing subscription whenever you import recipients.

Several possible solutions are available.


Expand
titleClick here to expand and see available solutions and recommended methods
FTP based integrations

You can request your MailUp representative for an FTP Batch Process for massive data transfer using files CSV files. This feature can be used for very large amounts of recipients (this kind of process has been successfully tested with 4 million recipients in a single file).

Expand
titleClick here to know more about available FTP transfer types

You can request this feature to

Data transmission does not take place in real-time: it is usually configured on a daily or weekly basis, but for specific cases, even an hourly schedule can be considered )

FTP-based integrations can also be customized to import external campaign codes ( meant as customer’s application internal campaign or recipient identities )   without using personal data fields and to export email statistics with their reference to the external campaign code. This feature is not available with MailUp web services. More on this.

REST API

Rest API allows immediate and bidirectional import and export of recipients. Due to restrictions on the HTTP channel, you cannot pass more than 7MB as a payload of a single call. To overcome this limit, you may either split your list into multiple calls or provide a large file to be uploaded using FTP (the latter is the recommended option in case of a very large data set). The REST API is the only MailUp solution that allows the removal of a single recipient from a group.

Expand
titleClick here to expand for recommended methods


Action

Comments

REST Web Services

Confirm successful communication with the API

Returns authentication information.

GET /Console/Authentication/Info

Retrieve Lists

Retrieves all lists related information

GET /Console/User/Lists

Retrieve GroupsRetrieves groups for a certain list

GET /Console/List/{ID_LIST}/Groups

Retrieve Fields

Retrieves the actual personal data field names along with ids. Useful for adding or updating subscribers’ personal information afterward.

GET /Console/Recipient/DynamicFields

Bulk Subscribe

Subscribes a set of recipients to a list

POST /Console/List/{id_List}/Recipients or
POST /Console/Group/{ID_GROUP}/Recipients

Bulk Unsubscribe

Unsubscribes a set of recipients from a list

POST /Console/List/{id_List}/Recipients?importType='asOptout'

Bulk Update

Updates personal data fields of a set of recipients

POST /Console/List/{id_List}/Recipients or
POST /Console/Group/{ID_GROUP}/Recipients

Retrieve the list of subscribers

Retrieves recipients that subscribed to a certain list

GET /Console/List/{ID_LIST}/Recipients/Subscribed



Use confirmed opt-in (COI)

Management of new subscribers (single or bulk) is specified in the section above. In some cases, you may need to verify if the email addresses and allow subscription only to existing email addresses that belong to subscribers that want to receive messages from the MailUp list they subscribed to. This case is also called double optin and subscribers have to click on a specific link that is contained in an email message that is sent to them after their signup.

Double opt-in is useful when your application does not check if the email addresses are valid.


Expand
titleClick here to expand and see how you can implement COI
HTTP GET/POST and subscription forms

Two HTTP GET/POST methods, (subscribe.aspx and xmlsubscribe.aspx) use confirmed optin by default, they can be used for single recipients. After signup, the subscriber receives the default confirmation request message that is configured for the specified MailUp list. Please refer to the documentation of HTTP GET/POST for more details.

REST API

At the moment Rest API supports the COI process using a query string parameter called "ConfirmEmail" that applies to POST calls to Console/List/{ListID}/Recipient and Console/Group/{GroupID}/Recipient endpoints. When this parameter is set as true, the actual behavior can be different if a specified recipient already exists:

  • new recipient -> added as pending, confirmation request email is sent

  • already subscribed -> no change

  • already pending -> remains pending, confirmation request email is sent

  • already unsubscribed -> moved to pending status, confirmation request email is sent

Manage suppression lists (i.e. "do not email" lists of recipients)

Suppression lists are not natively supported by MailUp but you can create a dedicated group of recipients to exclude from sending. To automate the process, you can contact the MailUp support department and request for the configuration of an FTP-based integration with a batch process running hourly. This process has to be set to import in a new group ( where the destination group name matches the actual import file name) the recipients that are listed in the file to be imported. Then, when you access to MailUp admin console, you can schedule or fire your campaign to be sent to "all subscribers except for the recipients that belong to a certain group". It should be easy for you to identify the right group because it has the name of the imported file plus a timestamp.

 

Send transactional and other personalized emails

SMTP or API: it's your choice

Sending messages through MailUp from an external application allows you to take advantage of:

  • The high reputation and scalability of the MailUp sending infrastructure
  • Automatic bounce and feedback loop management
  • Ability to include dynamic tags and dynamic content
  • Ability to check the send status via API

You can send transactional emails:

Message personalization

You can personalize messages using either data that already exists in the MailUp recipient database (and merge tags that will retrieve that data) or bypassing value pairs to the system. This is supported using both the SMTP relay and the API.

Bulk email messages

This section describes the different ways through which MailUp can be used to send email messages to groups and lists of users without accessing the administration console. The methods described above can be used to send individual, personalized messages, such as transactional emails. However, if the goal is to send large amounts of messages or DEMs, the best practice to follow is described below.

Some possible scenarios are presented here - with the indication of the web services to be used - as examples of common scenarios. This is in no way an exhaustive overview of all the possible scenarios. 

Please note that these cases do not talk about authentication and authorization, you should refer to the specific documentation of each technical solution for these details.


Expand
titleCase 1: email message and recipients exist in the MailUp admin console (click here to expand)

You may want to send a message to a group of users and both the message and the recipient's list are already available in the MailUp console.

REST API
  1. If the message has to be sent to all the recipients in a list you can call POST /Console/List/{id_List}/Email/{id_Message}/Send.
  2. If the message has to be sent to a group of a MailUp list you can call POST /Console/Group/{id_Group}/Email/{id_Message}/Send

 The message, group, and list IDs can be found at the page Settings > Codes or they can be retrieved using API.


Expand
titleCase 2: not all recipients exist in the MailUp admin console (click here to expand)

Similar to Case 1, but in this case, a group of recipients has to be imported as well. Some of these recipients might be already subscribed to MailUp due to the previous signup to a newsletter, some others might be new subscribers. Here below some alternative solutions are listed, refer to Comparison Matrix to see how many recipients can be loaded with each solution.

REST API

REST API supports only sending to a single group or the whole list

  1. To import recipients into a group of a MailUp list you may use POST/Console/Group/{ID_GROUP}/Recipients, while POST /Console/List/{id_List}/Recipients can be used to simply import into a MailUp list without specifying a group. Use  POST  /Console/List/{ID_LIST}/Group if you also need to create a new group. 
    1. the list of recipients can be provided in the request body or by specifying the name of a file you have previously uploaded via FTP. Refer to this page for more details
  2. Use the methods listed in Case #1 for sending an email message with REST API
FTP

You can use FTP-ZIP to upload a zip archive containing the list of recipients, the message content, and a file descriptor with the mailing instructions. After the upload, MailUp does all the rest, preparing and scheduling the mailing process. Since the whole process is fully asynchronous, you can add an email address in the file descriptor to be notified when the process is completed

LIST+

List+ allows you to enclose a list of recipients to the message to be sent (by using a file named one2many.import) instead of sending to lists or groups that are already present in MailUp. Click here for more information about this feature


Expand
titleCase 3: creating and sending a message via the MailUp API (click here to expand)

In some cases, it may be necessary to import into MailUp a message created using an external system.

REST API

With the REST API, you can fully handle message tags, images, and attachments.

  1. To create a message using POST /Console/List/{id_List}/Email, passing message content as a parameter. Check out this page to know more about the available options
  2. Use the methods listed in Case #1 for sending an email message with REST API
LIST+

With List+ you can create an email message with your email client or your application and send it to a MailUp specific email address. Depending on the specified address, this action can lead to

  • save email message to MailUp and send it to all the recipients of a MailUp list
  • save email message to MailUp and send it to all the recipients of one or more groups in a MailUp list
  • save email message to MailUp without sending it
  • save email message to MailUp and send it to a recipient for test purposes

This solution is very powerful if you want to work outside the MailUp console account and it has some interesting additional features like the automatic upload of images, support for dynamic fields, and sender verification. In addition, List+ allows you to enclose a list of recipients (by using a file named one2many.import) instead of sending it to existing lists or groups.


Expand
titleCase 4: cloning a message to track separate mailings (click here to expand)

Most customers need to track campaign results. When the same message is sent more than once (e.g. three different times, to three different groups), the results are linked to the message ID, not to the individual mailings. If you need to have distinct results for each mailing, you can make a copy of the message before sending it again. 

REST API

You can use GET /Console/List/{id_List}/Email/{id_Message} to get message content and then you need to create an identical message with POST /Console/List/{id_List}/Email


Expand
titleCase 5: massive sending of personalized messages via Web Services (click here to expand)

If you are in need to send a high number of personalized messages through the API, please refer to the section of "Transactional emails" or contact us.

REST API and List+

You can create personalized sections within your email using the Dynamic Content feature and MailUp filters. Dynamic Content is not available with email messages sent with HTTP GET/POST API and SMTP+


Send Transactional or Bulk SMS

...

As for the email channel, the term "transactional SMS" is usually used to distinguish messages that do not belong to "Promotional" or "Bulk" categories.

...

.

Note

Please check this page for regulations and limitations when sending SMS globally.


Expand
titleClick here to expand and see available methods
SOAP
REST API, FTP

SOAP API offers a The REST APIs offer reliable and scalable solution solutions for transactional SMS with SendDirectSMS, while other solutions are available for and Bulk SMS, including . In addition, bulk sending can also be performed with the "SMS sending from CSV file" feature that is provided for bulk sending , which uses FTP data transfer to allow massive sending of highly personalized text messages using FTP. REST API does not support SMS yet.

The following table includes the recommended API methods to be used to perform certain tasks.

Num.ActionDescription
SOAP
REST APIFTP
1Create a new text messageCreate a new text message with dynamic fields (optional) that can then be used as an "existing message"
fro
from the actions listed below
(MESSAGE_ID is returned).
New
A new message is also available on the MailUp console.
CreateSMS
Createamessage
 

2Single sending of EXISTING messages
to a specified recipient 		A single existing text message is sent to a single recipient by specifying MESSAGE_ID and destination number.
Message
A message shall be previously created and it can be customized
by means of
using dynamic fields
SendSingleSMS3Single sending of NEW messages
to a specified recipient In this case existing messages cannot be used, a brand new text message (with or without dynamic fields) has to be created
and sent to a single recipientSendDirectSMS 
SingleSend
 

3TRANSACTIONAL single sending
to a specified recipient 		High personalization of messages, suitable for high volumes, effective data aggregation, no need to save content on MailUp consoleTransactional SMS using APIs
4Bulk sending of EXISTING messages
to all subscribers or groups of them

A single existing text message is sent to many recipients (e.g. all list subscribers, one or more groups ...). by specifying
MESSAGE_ID and List/group identifiers

Message

A message shall be previously created and it can be customized

by means of

using dynamic fields

SendSMS
Sendtogroup/list
 

5Bulk sending of NEW messages
to all subscribers or groups of them

A new text message (with or without dynamic fields) has to be created and sent to a list of subscribers.

Note

Each action of this type creates a new message on the MailUp admin console.
The greater is the number of

 messages

messages and the higher is the load on the MailUp admin console, leading to


slowering

lowering access time to web pages and response time of web services. Please use alternative solutions
provided

in

on this page if you have to make more than ten actions of this type per day

CreateSMS  


Createamessage +

SendSMS
or SendSmsFast

 Sendtogroup/list 


6Bulk sending of NEW messages
to a list of recipients with a specific
text message for each recipient

In some cases, customization through dynamic fields could be not enough
A list of {recipient + message text for this recipient} has to be provided as input and all messages shall be sent as a single campaign.
This option has not had the side effects of option #5 and it also allows sending of completely different messages for each recipient.

N/ASMS sending from CSV file
7Immediate sendingFor text messages to be sent as soon as possible
SendSingleSMS

Createamessage 


SendDirectSMS  
SendSMS
SendSmsFast

+

Sendtogroup/list 

SMS sending from CSV file 
8Scheduled sendingFor text messages to be sent at a specified time
SendSMS
SendSmsFast

Createamessage +

Sendtogroup/list 

SMS sending from CSV file 
9Sending of concatenated messagesWhen message length is higher than 160 characters (or higher than 70 chars if "Unicode" (use Unicode for non-western alphabets)
SendSingleSMS 
SendDirectSMS  
SendSMS
SendSmsFast SMS sending from CSV file 

...

Createamessage +

Sendtogroup/list 

SMS sending from CSV file 
10Read Available creditsRetrieve the value of remaining credits (either as a whole at the account level or by list)N/A
11SMS Price

To know how many credits are used when sending an SMS in any country, visit SMS Credits & SMS Price




Extractor display statistics

Email statistics are mainly the number and the details about opens and clicks, usually grouped by message. About SMS we can only know the delivery status and, in case of error, the error code.  

...

Expand
titleClick here to expand and see available methods
REST API

REST API offer offers the best suite about of MailUp statistics, also allowing filtered and paged searches. More on this page  

FTP

A batch export can be configured to periodically export to a CSV file the statistics of email and/or SMS messages. Export frequency can be set for hourly to forth fourth weekly schedules. Contact us to request for a batch export for your console account (non-standard configurations may require an extra fee). More on this page

SOAP API 

WebService MailupReport provides a couple of methods to retreive statistics by message or by recipient. This solution runs fine only when returned data size is relatively small (e.g. lower than 100 items)

Frontend

Frontend pages provide a reduced version of some statistics pages of the console account , so that an external application can embed them. Available pages are similar to Summary Report and Opens report.

...