...
...
...
...
title | Plan your integration |
---|
...
Start choosing the use cases that better fit your needs and then select a technical solution that covers your requirements. For each use case listed below, more technical solutions may be available, but they differ in some aspects. Check them out and follow the links they contain. A wide comparison matrix between available techincal solutions is available here.
On this page:
Table of Contents maxLevel 4
Manage single recipients (subscribe, unsubscribe, update)
MailUp provides several ways to add a new subscriber and manage either data fields or subscription status.
Expand | ||
---|---|---|
| ||
HTTP GET/POST and subscription formsSubscription forms are based on HTTP GET/POST methods, which allow subscription unsubscription, check subscription status and update for a single recipient. These methods supports optin, confirmed optin, optout, fields update, unsubscription REST APIRest API is the most complete solution for managing a single subscriber (subscription status, group mebership 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. WebhooksYou 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 APIYou 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 a new recipient is an asynchronous process. |
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, subscription 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
Expand | |||||
---|---|---|---|---|---|
| |||||
FTP based integrationsYou 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.
SOAP APIYou 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, since it does not allow export of recipients. SOAP API + FTPYou can get the best of FTP and SOAP API by using SendMessageNL API method, which performs scheduled sending to a group of recipients that is specified on a file. 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 APIRest 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)
You can contact MailUp support and ask 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 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.
Expand | ||
---|---|---|
| ||
SOAP APIYou 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 + FTPEmail 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 APIEmail 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:
FTPSMS 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 |
Send transactional emails/SMS
The term "transactional" is usually used to distinguish messages that do not belong to "Promotional" or "Bulk" categories.
Expand | ||
---|---|---|
| ||
SMTP+Email only. SMTP+ offers a scalable solution that is valid also for high volumes of transactional email messages to be sent. Delivery time depends on the bandwidth agreed for that console account. SOAP APISOAP API offers a good and scalable solution for transactional SMS with SendDirectSMS, while for email you can use SendSingleNewsletter or SendNewsletter but you must be aware of the existing limitations (refer directly to the documentation of these methods or check out the API use policy |
...
Info |
---|
This page contains many collapsed sections that contain details about recommended methods in REST, HTTP GET/POST API. Use the "Click to expand" links to reach hidden parts. |
On this page:
Table of Contents | ||
---|---|---|
|
...
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 always making use of the “retrieve field names” feature, returning the actual field names and Id occurrences for a particular admin console account. Those returned occurrences can be used to update personal data recipient fields afterward.
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
HTTP GET/POST and subscription formsSubscription 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. The retrieve fields feature is not available with HTTP GET/POST.
REST APIRest API handles subscription status, group membership, and personal data fields. 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). 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.
WebhooksYou can configure webhooks to enable a fast callback to your website every time a recipient changes the subscription status or any of the personal data fields (e.g. by filling in and submitting to an auto profile form). The callback method can be configured 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. |
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 | |||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||
FTP based integrationsYou 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).
REST APIRest 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.
|
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 | ||
---|---|---|
| ||
HTTP GET/POST and subscription formsTwo 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 APIAt 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:
|
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 | ||
---|---|---|
| ||
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
The message, group, and list IDs can be found at the page Settings > Codes or they can be retrieved using API. |
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 APIREST API supports only sending to a single group or the whole list
FTPYou 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 | ||
---|---|---|
| ||
In some cases, it may be necessary to import into MailUp a message created using an external system. REST APIWith the REST API, you can fully handle message tags, images, and attachments.
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
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 | ||
---|---|---|
| ||
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 APIYou 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 | ||
---|---|---|
| ||
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
REST API, FTPThe REST APIs offer reliable and scalable solutions for transactional and Bulk SMS. In addition, bulk sending can also be performed with the "SMS sending from CSV file" feature, which uses FTP data transfer to allow massive sending of highly personalized text messages. The following table includes the recommended API methods to be used to perform certain tasks.
|
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 | ||
---|---|---|
| ||
REST APIREST API offer offers the best suite about of MailUp statistics, also allowing filtered and paged searches searches. More on this page FTPA batch export can be configured to periodically export on to a CSV file the statistics of email and/or SMS messages. Export frequency can be set from 1 hour to 2 weeksfor hourly to fourth weekly schedules. Contact us to ask request a batch export for your console account (non-standard configurations may require an extra fee). SOAP APIWebService 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) More on this page FrontendFrontend 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. |
...