MailUp API
Page tree

Versions Compared

Old Version 6

changes.mady.by.user MailUp Dev Team

Saved on

compared with

New Version 7

changes.mady.by.user MailUp Dev Team

Saved on

Key

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

...

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

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.

...

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 . Please and authorization, you should refer to the related specific documentation of each technical solutions for these details on authentication.

 

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

 

Expand
titleCase 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
  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 are just 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 users matching a certain condition are automatically included in the filter results, whereas a user must be inserted into a group for group membership.

 

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:

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

    Expand
    titleCase 2: not all recipients exist in the MailUp admin console

    Check out the documentation of SOAP API for more details.

     

    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 retreived using API. Optionally, you can specify also sender name or sender email if you want to use for that message a sender that is different 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

    Expand
    titleCase 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
    1. 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(). 

    2. 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:
      1. Creation of a temporary group named "Automatic NN", where NN is a progressive number
      2. Import to this group of the recipients indicated in the file
      3. Sending of the message at the scheduled time and date

    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

    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
    2. Use the methods listed in Case #1 for sending email message with REST API
    Expand
    titleCase 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.

    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.

    Note

    Please take care when using methods that creates a new message on MailUp admin console (i.e. each call to CreateNewsletters and SendNewsletterFast,but also calls to SendSingleNewsletter when content is not based on existing message ID). 
    The  The greater is the number of messages and the higher is the load on MailUp admin console, leading to slowering access time to web pages and response time of web services. Please use alternative solutions
    provided in this page or contact us if you have to make more than ten actions of this type per day

     

    REST API

     

    LIST+

     

    smtp+
    Expand
    titleCase 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 using the CloneMessage() method: 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). 

    Note
    Note that when using web services it is not possible to manage the import of external campaign codes: this operation requires an import via batch FTP. More on this.
    Expand
    titleCase 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. 

     

    ...

    Expand
    titleClick here to expand and see available methods
    SOAP API

    SOAP 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

    ...

    Expand
    titleClick here to expand and see available methods
    REST API

    REST API offer the best suite about MailUp statistics, also allowing filtered and paged searches  

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

    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.

    ...

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