On this page:
Manage single recipients (subscribe, unsubscribe, update)
MailUp provides several ways to add a new subscriber and manage either data fields or subscription status. When developing generic modules that should adapt to different console accounts with different fields mapping, it is useful that you take advantage of a "retrieve fields" feature, which gets from MailUp field ID and field name and allows mapping between fields in the MailUp account and those in the integrated application.
Click here to expand and see available methods for handling single recipient
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 fields feature is not available with HTTP GET/POST.
Click here to expand for more details...
Action | Comments | Get/Post API |
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 a single customer 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 a single customer to one or more lists (e.g. during checkout or registration) and returning a result to the caller | Xmlsubscribe.aspx |
Single Unsubscribe (server side1) | Unsubscribing a single customer 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 a single customer based on mapped data fields (e.g. first name, last name, etc) and returning a result | XmlUpdSubscriber.aspx |
Retrieve subscription status for a specific customer and list (server side1) | This refers to determining whether a certain customer is subscribed to a given list or not, so that the correct subscription preference can be shown in the ecommerce system (or to update locally stored subscription preferences). | XmlChkSubscriber.aspx |
(1) requires server side development, 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 (subscription status, group membership and personal data fields) and it is the only MailUp solution that allows removal of a single recipient from a group. Adding a new recipient 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). Retreive fields feature is available with GET /Console/Recipient/DynamicFields
Webhooks
You can configure webhooks to enable a fast callback to your website when a recipient changes the subscription status or the personal data fields (e.g. by accessing to an autoprofile form). Callback method can be configured in order to include recipient's details as 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 StartImportProcess method of MailUpImport SOAP API, that is designed for bulk import, to work with a single recipient. This method supports 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.
Synchronize recipients between your application and MailUp (i.e. bulk import and/or export)
You may need to transfer a set of recipients, eventually 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 numbers of recipients, in this case bulk solutions are needed.
When defining your synchronization strategy 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 managed by MailUp with the "Unsubscribe" link in email footer (that's the default case), forcing subscription should be consider only when an unsubscribed recipient asks to be subscribed again
- If unsubscription is managed by an external system (i.e the "Unsubscribe" link in email footer leads to an external site) then the external application is the "master" and you should consider to force subscription whenever you import recipients.
Several possible solutions are available
Click here to expand and see available methods
FTP based integrations
You can use FTP Batch Processes for massive data transfer using files in CSV format. This feature can be used with very high numbers of recipients (import has been successfully tested with 4 millions of recipients in a single file) and it is configured on request by MailUp support team.
Click here to know more about available FTP transfer types
You can request this feature to
Data transfer is not in real time: it is usually configured as daily or weekly, but for specific cases even hourly data transfer can be done)
FTP based integrations can also be customized to import external campaign codes 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 use MailUpImport SOAP API for an immediate import of recipients. In particular, you can use StartImportProcess method, eventually combined with NewImportProcess if the number of recipient is higher than 5000. These methods also allow a batch import as "pending", with the confirmation email that has to be manually sent using the adimin console account. SOAP API is not bidirectional, so you cannot use it to export recipients from MailUp to your application.
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 listed on a file (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 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 can be uploaded with a single import. For the export of recipients the paging feature is recommended to keep control on maximum size of tranferred data. REST API is the only MailUp solution that allows removal of a single recipient from a group
Manage suppression lists (i.e. "do not email" lists of recipients)
Suppression lists are not natively supported by MailUp but you can create a group of recipients and exclude this group from sending. In order to automate the process, you can contact MailUp support department and ask for the configuration of an FTP based integration with a batch process that is configured to run hourly. This process has to be set to import in a new group (group name = file name) the recipents that are listed in the file to be imported. Then, when you access to MailUp admin console, you can schedule 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 very quickly, thanks 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).
- Automatic processes can be activated following actions that users 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).
Click 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 choose between them 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 edited, so to make it correspond to the template of the message you want to send (there is only one confirmation message 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 emails can also contain a link triggering an action (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, but it is paramount to 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), but 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.
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.
Case 1: email message and recipients exist in the MailUp admin console
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
- 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.
- If the recipients are just some groups in a list, when calling the SendNewsletter() method the group IDs must be specified as well.
- 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 users matching a certain condition are automatically included in the filter results, whereas a user must be inserted into a group for group membership.
REST API
- 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.
- 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
Case 2: not all recipients exist in the MailUp admin console
Similar to Example 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
- Through WS_MailUpImport methods a new temporary group is created (CreateGroup(groupName)) and a group of recipients is imported to it (StartImportProcess(groupID, recipients,…)). This operation may last several minutes, depending on how large the group is, and it can be monitored using GetProcessDetails(). Once the import is finished, SendNewsletter(groupID) method can be used to perform the sending. At the end of the process the group which was created for the purpose must be deleted using DeleteGroup().
- The procedure described here above is less effective when there are large amounts of data to be imported, so it may be useful to use an alternative procedure that provides for a "bulk" import from a file following an input via web service. SendMessageNL(fileName, listId, messageId, timeDateSending,…) method allows to schedule a sending for the desired time and date, then asynchronously executes the following operations:
- Creation of a temporary group named "Automatic NN", where NN is a progressive number
- Import to this group of the recipients indicated in the file
- Sending of the message at the scheduled time and date
REST API
REST API supports only sending to a single group or to the whole list
- 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
- Use the methods listed in Case #1 for sending email message with REST API
Case 3: creating and sending a message via the MailUp API
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.
- 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
- 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 on MailUp and send it to all the recipients of a MailUp list
- save email message on MailUp and send it to all the recipients of one or more groups in a MailUp list
- save email message on MailUp without sending it
- save email message on 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.
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 on MailUp and delivery speed depends on agreed bandwidth for your account.
Case 4: cloning a message to track separate mailings
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 get around this issue, you can make a copy of a message by cloning it: once the copy has been created, the sending can be performed as described above as this is treated as a completely new mailing for a completely separate message (even if the actual message being sent is identical to another one).
SOAP API
You can use using the CloneMessage() method
REST API
You can use GET /Console/List/{id_List}/Email/{id_Message} to get message content and then you can create an identical message with POST /Console/List/{id_List}/Email
Case 5: massive sending of personalized messages via Web Services
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 is specific 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.
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.
Click here to expand and see available methods
SOAP API, FTP
SOAP API offers a good and scalable solution for transactional SMS with SendDirectSMS, while other solutions are available for Bulk SMS, including "SMS sending from CSV file" feature that is provided for bulk sending 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. | Action | Description | SOAP API | Other methods |
---|
1 | Create new text message | Create a new text message with dynamic fields (optional) that can then be used as "existing message" fro the actions listed below (MESSAGE_ID is returned). New message is also available on MailUp console. | CreateSMS | |
2 | Single 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 shall be previously created and it can be customized by means of dynamic fields | SendSingleSMS | |
3 | Single 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 recipient | SendDirectSMS | |
4 | Bulk 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 shall be previously created and it can be customized by means of dynamic fields | SendSMS | |
5 | Bulk 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.
| CreateSMS + SendSMS or SendSmsFast | |
6 | Bulk 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 the side effects of option #5 and it also allows sending of completely different messages for each recipient. | N/A | SMS sending from CSV file |
7 | Immediate sending | For text messages to be sent as soon as possible | SendSingleSMS SendDirectSMS SendSMS SendSmsFast | SMS sending from CSV file |
8 | Scheduled sending | For text messages to be sent at specified time | SendSMS SendSmsFast | SMS sending from CSV file |
9 | Sending of concatenated messages | When 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 |
Extract or 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.
Click here to expand and see available methods
REST API
REST API offer the best suite about MailUp statistics, also allowing filtered and paged searches. More on this page
FTP
A batch export can be configured to periodically export on a CSV file the statistics of email and/or SMS messages. Export frequency can be set from 1 hour to 2 weeks. Contact us to ask 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 works well 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.
Send email/SMS campaigns from your application (e.g. CRM or CMS)
To manage your campaign with MailUp you need to import (subscribe) the recipients first. Refer to section above to discover how to move recipients from your an external application to MailUp. Campaign messages can be created using API or you can use messages that were previously created through admin console account.
Since email statistics are aggregated by message, be aware that when you reuse a previously sent message then it is likely that you will not be able to split the aggregated statistics. You can make a copy of the message instead of reusing it.
Click here to expand and see available methods
SOAP API
You can use CreateNewsletter to create a new email message, Clone Message to make a copy of an existing one and finally you can use SendNewsletter to program an immediate or scheduled sending (at sending time you will be able to specify who will receive that campaign). For SMS you can use a similar approach with CreateSMS and SendSMS methods. Since SMS statistics are very poor when compared to email, there was no need to implement a "clone SMS" method
SOAP API + FTP
Email only. As an alternative to importing recipients and then calling SendNewsletter , method SendMessageNL allows a bulk import and the scheduling of a specified email message with a single operation. Refer to method documentation to learn more about this method and its known limitations
REST API
Email only. REST API offers the most complete suite form creating and managing an email message, but it still has some limitations about sending that are going to be removed in some of the next product releases:
- scheduled sending is not yet supported (only immediate sending to all subscribers or to specified groups/recipients)
- recipient selection by applying filters is not available
- capability of immediate delivery (e.g. for confirmation messages) regardless what else is happening in the delivery queue at that time is not supported
FTP
SMS Only. FTP solution offers the capability to import (bulk) recipients and send them SMS messages that can be fully customized for each recipient. Refer to "Text message (SMS) sending from .CSV file" for more info.
LIST+
Email only. You can create an email message on your application (or email client) and send it to a specified MailUp address. According to the specified email address you can simply save message on MailUp (images are also saved on MailUp space), send it to a test recipient or send the message to a list/group