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

maxLevel	4

...

Expand

title	Click 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 fields feature is not available with HTTP GET/POST.

Expand

title	Click here to expand for recommended methods

Action	Comments	Get/Post API
Confirm successful communication with the API	This 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)	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 side¹)	Subscribes a single recipient to one or more lists (e.g. during checkout or registration) and returning a result to the caller	Xmlsubscribe.aspx
Single Unsubscribe (server side¹)	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 side¹)	Updates a single recipient 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 side¹)	Retrieves recipient’s status ( subscribed, pending or unsubscribed )	XmlChkSubscriber.aspx

(1) requires server side development, and in 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 (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). Retrieve fields feature is available with GET /Console/Recipient/DynamicFields

Expand

title	Click here to expand for recommended methods

Action	Comments	REST API
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 Groups	Retrieves 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 afterwards.	GET /Console/Recipient/DynamicFields
Single Subscribe	Subscribes a single recipient to one lists (e.g. during checkout or registration). Confirmed optin process can be implemented by means of ConfirmEmail parameter	POST Console/List/{ListID}/Recipient (without COI) POST Console/List/{ListID}/Recipient?ConfirmEmail=true (with COI)
Single Unsubscribe	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	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	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 a recipient changes the subscription status or any of the personal data fields (e.g. by filling in and submitting 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 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

title	Click here to expand for recommended methods

Action	Comments	SOAP Web Services
Confirm successful communication with the API	This method has to be used to authenticate the admin console user against the web service.	MailUpSend.LoginFromId
Retrieve Lists	Retrieves all lists related informaton
Retrieve Groups	Retrieves groups	MailUpImport.GetNlLists or WS_MailUpSend.GetGroups
Retrieve Fields	Retrieves the actual personal data field names along with ids. Useful for adding or updating subscribers’ personal information afterwards.	MailUpSend.GetFields
Single Subscribe	Subscribes a single recipient to one or more lists (e.g. during checkout or registration)	MailUpImport.StartImportProcesses
Single Unsubscribe	Unsubscribes a single recipient from one or more lists (e.g. customer updates their account in the storefront)	MailUpImport.StartImportProcesses
Single Update	Updates 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	N/A	N/A

...

Expand

title	Click 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 confimation 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 by means of a querystring 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 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

SOAP API

With StartImportProcess method of MailUpImport SOAP API you can use a "Confirm" flag to import recipients as pending and prepare sending of a confirmation request email. Please note that this message for pending recipients is added but not sent by API, you must enter into your MailUp admin console to proceed with sending.

...

This is supported using both 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 solutions for these details.

Expand

title	Case 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

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 belong to 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 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

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

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

Expand

title	Case 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

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 has completed, 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 above described 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

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

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

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

Note

It is very relevant 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.
Use methods that creates a new message on MailUp admin console sparingly (i.e. each call to CreateNewsletters and SendNewsletterFast,but also calls to SendSingleNewsletter when content is not based on existing message ID). The greater is the number of messages and the higher is the burden 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

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

title	Case 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

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

...

Expand

title	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 to a CSV file the statistics of email and/or SMS messages. Export frequency can be set for hourly to forth 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.

...

Versions Compared

Old Version 29

New Version 30

Key

HTTP GET/POST and subscription forms

REST API

Webhooks

SOAP API

HTTP GET/POST and subscription forms

REST API

SOAP API

Bulk email messages

SOAP API

REST API

SOAP API

REST API

LIST+

SOAP API

REST API

LIST+

SMTP+

SOAP API

REST API

SOAP API, REST API and List+

SMTP+

REST API

FTP

SOAP API

Frontend

Page Comparison

Versions Compared

Old Version 29

New Version 30

Key

Manage single recipients (subscribe, unsubscribe, update)

HTTP GET/POST and subscription forms

REST API

Webhooks

SOAP API

HTTP GET/POST and subscription forms

REST API

SOAP API

Bulk email messages

SOAP API

REST API

SOAP API

REST API

LIST+

SOAP API

REST API

LIST+

SMTP+

SOAP API

REST API

SOAP API, REST API and List+

SMTP+

REST API

FTP

SOAP API

Frontend