This page provides you information about how to manage recipients (subscribe, unsubscribe, update personal data).
On this page:
New to MailUp?
Confused with MailUp terminology? Please take a moment to review the Definitions and Recipients Management sections.
A few definitions and important notes:
- Email Recipient: The person whose email address - and optionally other data - is added to MailUp.
- Email Recipient Status: A recipient's status may be subscribed, not subscribed, unsubscribed, or pending (i.e. pending subscription confirmation). A MailUp account can contain multiple Lists (e.g. "Monthly Newsletter", "Daily Specials", etc.). Status is List-specific.
- Email Subscriber: An email recipient whose status is "Subscribed"
- Subscription management is List-specific: Since Status is List-specific, the action to subscribe/unsubscribe is also list-specific. To subscribe/unsubscribe to/from multiple Lists you have to perform one subscribe/unsubscribe action for each target List.
- COI (Confirmed Optin, also known as double opt-in): A confirmed opt-in subscription process - a best practice in email marketing - is enforced only when explicitly requested via the ConfirmEmail parameter. When COI is enabled, a subscription request message is sent automatically. The content of that message can be found - and fully customized - in the list settings of your MailUp admin console.
Manage a single email recipient / subscriber
Add a single recipient / subscriber (synchronous import)
A single recipient can be added to a console account by calling the following methods:
- POST /Console/List/{id_List}/Recipient
- POST /Console/Group/{id_Group}/Recipient
You can choose to perform a double optin procedure for the given recipient by adding the querystring parameter "ConfirmEmail=true": in this case the recipient will be added to the given list/group in "Pending" status, and a confirmation email will be sent to that address, waiting for his/her confirmation. You can also update the information and status of an existing recipient by specifying his/her email address or mobile number as unique identifier of the existing recipient.
Description | Retrieve recipient dynamic field definitions. |
---|---|
HTTP Method | POST |
URL | You can add a new recipient to a Console account, adding it to a specific List or a specific Group, by calling the following methods: POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Recipient If you add a recipient to a group, automatically it will be added to the list related to that group. POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{id_Group}/Recipient To enable Confirmed Opt-In (COI) the querystring parameter ConfirmEmail must be set to true POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Recipient?ConfirmEmail=true POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{id_Group}/Recipient?ConfirmEmail=true |
JSON request (example) | |
JSON response (example) | Recipient ID is returned (e.g. 77)
|
Paging and filtering (example) | none
|
Update personal data fields of a subscriber
This section refers to changes to a specific subscriber's personal data field (the subscriber must already exist)
The update operation requires:
- Recipient ID, which can be retrieved with the operation listed above (Check if a subscriber exists)
- The IDs of the fields to be updated
Description | Retrieve recipient dynamic field definitions. |
---|---|
HTTP Method | PUT |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Recipient/Detail |
JSON request (example) | |
JSON response (example) | |
Paging and filtering (example) | none
|
Update subscription status of a recipient
You can change the subscription status of an existing recipient on a specified List via the API. Unsubscription via the REST API can only be performed with this method. A bulk unsubscription method is not yet available.
Update operation requires
- Recipient ID (refer to section "Check if a subscriber exists")
- List ID
POST operation described in this section has been designed only to extend subscription to another list (e.g. recipient with ID=21 is already subscribed to list 1 and I want to add it also to list 2 -> POST /Console/List/2/Subscribe/21).
The function here described cannot be used to force subscription of unsubscribed recipients: the only way to subscribe again an unsubscribed recipient is to import it with double optin (i.e. imported as pending with confirmation request email e.g. POST /Console/List/2/Recipient?ConfirmEmail=true)
Description | Add/remove the recipient with the related id in the List specified. |
---|---|
HTTP Method | POST/DELETE |
URL | Subscribe POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Subscribe/{id_Recipient}
Unsubscribe DELETE https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Unsubscribe/{id_Recipient} |
JSON request (example) | none |
JSON response (example) | none |
Paging and filtering (example) | none
|
Update group assignment
A group in MailUp is a subset of a list. Subscribe/unsubscribe is at the list level, not at the group level. Groups are typically used for segmentation purposes within a list.
You can use the API to assign or remove an existing recipient to/from a specified group. Removing a recipient from a group does not affect its list subscription status.
Update operation requires
- Recipient ID (see section "Check if a subscriber exists")
- Group ID
Description | Add/remove the recipient with the related id to the specified group |
---|---|
HTTP Method | POST/DELETE |
URL | Add POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{id_Group}/Subscribe/{id_Recipient}
Remove DELETE https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{id_Group}/Unsubscribe/{id_Recipient} |
JSON request (example) | none |
JSON response (example) | none |
Paging and filtering (example) | none |
Check if a subscriber exists
This method allows you to:
- verify whether a certain recipient is already a subscriber in a certain list within a specified MailUp account
- retrieve the recipientID and personal data fields for that recipient, if it is found
Known restriction
At this time unfortunately the REST API does not include a method to search a recipient by email address regardless the subscription status, within a specific list. To accomplish that at the moment you will need to run the same search three times for subscribed, unsubscribed and finally pending recipients.
Description | Check subscriber and retreive data |
---|---|
HTTP Method | GET |
URL | see example in the "paging and filtering" row |
JSON request (example) | none
|
JSON response (example) | |
Paging and filtering (example) |
Manage Multiple recipients
If you need to add many recipients it is strongly recommended to use an asynchronous method instead of calling many times the single import method. Also COI option is availble for multiple recipients, in this case more method calls are required
Add/remove recipients (asynchronous import)
Asynchronous import is used to perform a bulk import of several recipients into the MailUp account. Since the process is not synchronous, it is fast, but not real time. Please check the import status in order to know whether the import task has been completed.
In case of bulk import, the upper limit for parameter size is configured to support an upload size that is about 7MB for each call. This limit approximately corresponds to 5,000 recipients with 27 personal data fields (upload time = 300s) or 50,000 recipients with only email field (upload time = 370s). In any case, we recommend to set a configurable upload size limit in your application and make a test with this size. When upload size exceeds this limit you can split the list of recipients in more blocks and perform more requests. When more import requests are pending, MailUp processes them in a sequential order.
The import process is able to recognize existing recipients (using the email address or the mobile number as unique identifiers), and update them according to the given input details. It is possible to add some querystring parameters to specify some advanced behavior for the import process:
- ConfirmEmail=true: if specified, sets the new recipients status to "Pending", and a confirmation email is generated (but not yet sent). Please check below in the section "Send Confirmation Email" the procedure to actually send the emails generated so far.
- importType=asOptout: if specified, the given recipients' status is set to "Optout", except for the ones already in “Pending” Status. A complete explanation of the available scenarios is provided below.
Description | Create and execute a task that imports specified recipients. Import task ID is returned |
---|---|
HTTP Method | POST |
URL | Import recipients into a list https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Recipients
Import recipients into a group (a group always belongs to a single list) https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{ID_GROUP}/Recipients |
JSON request (example) | |
JSON response (example) | 3 (import ID, a progressive number)
|
Paging and filtering (example) | none
|
Read Import Status
Description | Read status of an import task by specifying its ID. List ID is not required. |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Import/{IMPORT_ID} |
JSON request (example) | none
|
JSON response (example) | {"Completed":true,"CreatedRecipients":1,"ImportedRecipients":0,"NotValidRecipients":0,"UpdatedRecipients":0,"ValidRecipients":1,"idImport":3} |
Paging and filtering (example) | none
|
Send Confirmation Email
The confirmation emails (generated in the bulk import process as the result of "ConfirmEmail=true" querystring parameter) can be sent with the following process;
- Retrieve the SendingID of that confirmation email, with the following call, where {id_import} is the result of the current import call. The result of this GET call is a structure with the SendingID (idImport) and the number of generated emails (EnqueuedEmails).
GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Import/{id_import}/Sending
- Send the email immediately or planning a schedule by calling one of these methods where {id_sending} is the SendingID retrieved at previous step, with no body. Moreover a body like {Date:'yyyy-MM-dd HH:mm'} is required: for the "Deferred" case. NOTE: the specified date must be in UTC and at least 5 minutes in the future, with the format described in the section 'Type and cast definition' of "Paging and filtering" page
POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Email/Sendings/{id_sending}/Immediate POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Email/Sendings/{id_sending}/Deferred
Read personal data fields configuration
Any update of recipients' personal data fields requires the IDs of the fields to be updated. Resource /Console/Recipient/DynamicFields allows you to retrieve personal data fields settings for a specific MailUp account (number of fields, names and IDs).
Description | Retrieve recipient dynamic field definitions. |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Recipient/DynamicFields |
JSON request (example) | none
|
JSON response (example) | |
Paging and filtering (example) | Use endpoint /Console/Recipient/DynamicFields?PageNumber=0&PageSize=30&orderby="Id+asc" to get with a single response the full list ordered by Id, otherwise paging (20 items/page) is applied
|
Retrieve all subscribed/unsubscribed/pending recipients from a list
For each MailUp list and for each channel, these are the available subscription conditions:
- subscribed
- unsubscribed
- pending
- not subscribed (has one of the statuses listed above at least in another list of that account)
"Unsubscribed" and "pending" conditions apply only to lists, not to groups.
Read subscribed recipients on Email channel
Description | Retreive subscribers of specified list |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Recipients/Subscribed |
JSON request (example) | none |
JSON response (example) | |
Paging and filtering (example) | 2 items per page, get first page (count starts from zero)
Retreive all the subscribers of a specified list whose Email contains 'example' filterby="Email.Contains('example')" and sort them by Email orderby="Email asc". Parameter names can be retreived from the response body. Please note that "Contains" is case sensitive.
|
Read unsubscribed recipients on Email channel
As for "subscribed", but in this case the endpoint is /Console/List/{ID_LIST}/Recipients/Unsubscribed.
GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Recipients/Unsubscribed
Read pending recipients on Email channel
As for "subscribed", but in this case the endpoint is /Console/List/{ID_LIST}/Recipients/Pending.
GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Recipients/Pending
Retrieve recipients that belong to a group
A recipient can belong to zero, one or more groups of a list, regardless its subscription status in that list.
Read group members
Description | Retreive only email subscribers that belong to specified group. Group members that are not subscribed on email channel are not returned |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{id_Group}/Recipients |
JSON request (example) | none |
JSON response (example) | |
Paging and filtering (example) | 2 items per page, get first page (count starts from zero)
Retreive all the subscribers of a specified list whose Email contains 'example' filterby="Email.Contains('example')" and sort them by Email orderby="Email asc". Parameter names can be retreived from the response body. Please note that "Contains" is case sensitive.
|