...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Tip | ||
---|---|---|
| ||
Confused with MailUp terminology? Please take a moment to review the Definitions and Recipients Management sections. |
On this page:
Table of Contents |
---|
Read personal data fields configuration
Any update of recipients' personal data fields requires at least the IDs of the fields to be updated. Resource /Console/Recipient/DynamicFields allows you to retrieve personal data fields settings (numer of fields, their names and the ID for each of them) of your console account. .
Description | Retrieve recipient dynamic field definitions. | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL |
| |||||||
JSON request (example) | none
| |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) | Use endpoint /Console/Recipient/DynamicFields?&orderby="Id+asc" to get a list that is ordered by Id
|
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 status 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
...
Code Block |
---|
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Recipients/Subscribed |
...
JSON request (example)
...
none
...
JSON response (example)
...
language | html/xml |
---|
...
This page provides you information about how to manage recipients (subscribe, unsubscribe, update personal data).
On this page:
Table of Contents |
---|
Tip | ||
---|---|---|
| ||
Confused with MailUp terminology? Please take a moment to review the Definitions and Recipients Management sections. |
Info |
---|
A few definitions and important notes:
|
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.
Expand | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||
Based on the existing status, if available, and the ConfirmEmail parameter, the following scenarios hold true:
*Usually it does not matter if recipient is already subscribed/unsubscribed on another list, but be aware that a "key mismatch" may occur if recipient is already registered with a different phone number.In this casethe request is denied and no action applies |
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:
If you add a recipient to a group, automatically it will be added to the list related to that group.
To enable Confirmed Opt-In (COI) the querystring parameter ConfirmEmail must be set to 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 |
| ||||
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 in a specified List. To update multiple recipients at the same time, see Manage multiple recipients below.
Update operation requires
- Recipient ID (refer to section "Check if a subscriber exists")
- List ID
Note |
---|
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). |
Description | Add/remove the recipient with the related id in the List specified. | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST/DELETE | ||||||||||||||||||||
URL | Subscribe
Unsubscribe
| ||||||||||||||||||||
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
Remove from a group
| ||||||||||||||||||||||
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
Note | ||
---|---|---|
| ||
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 do one of the following:
|
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) |
---|
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.
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/1/Recipients/Subscribed?filterby="Email.Contains(%27example%27)"&orderby="Email+asc"
Read unsubscribed recipients on Email channel
As for "subscribed", but in this case the endpoint is /Console/List/{ID_LIST}/Recipients/Unsubscribed.
Code Block |
---|
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.
Code Block |
---|
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 |
| |||||||
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.
|
Asynchronous import of recipients
Asynchronous import is used either for adding a single recipient to MailUp or to perform a bulk import.
Since it's not synchronous, it is fast but not immediate, please check the import status in order to know when the import task is completed.
Note |
---|
In case of bulk import, the upper limit for parameter size is configured as 500MB for each call. In any case we recommend to set a configurable upload size limit in your application and make a test with this size. When parameter 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. |
Import recipients
...
Description
...
Create and execute a task that imports specified recipients. Import task ID is returned
...
HTTP Method
...
POST
...
Import recipients into a list
Code Block |
---|
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Recipients |
...
Manage multiple recipients
If you need to subscribe or unsubscribe multiple recipients it is strongly recommended to use an asynchronous method instead of calling many times the single import method. The Confimed Opt-in subscription method is availble in this mode by performing a few different API calls, as described below (see Send confirmation email).
Subscribe/unsubscribe recipients - asynchronous import
Asynchronous import is used to perform a bulk import of several recipients into the specified list. Since the process is not synchronous, it is fast and it immediately returns an import ID (without waiting for the end of the import process), but it's not real time and there cannot be two or more imports at the same time with a single MailUp account. A HTTP 500 error with description="Resource internal error. Another import is running" is returned when you try to do more import at the same time. Please check the import status in order to know whether the import task has been completed.
Note |
---|
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 somequerystringparameters 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.
clearMissingOrEmptyFields: when set to "true", the import process clears on MailUp field that is not specified or set as empty in the request body.
removeFromPrevGroups: when set to "true", first the import process removes the given recipients from any group they have been part of, then it adds them only to the group specified along with this request. This querystring parameter applies only to "Import recipients into a group" cases.
ignoreMobile: (RECOMMENDED if you are not going to send SMS) when set to "true", the import process ignores the MobileNumber and MobilePrefix fields. As multi-channel import is much slower than single-channel import (up to 60 times), you should avoid importing on both channels when it is not mandatory for your business goals.
fileName: accepts a recipients' list in a file format instead of passing it through the request body. This option is recommended when uploading a large amount of data with a single call (e.g. more than 10K recipients). Please refer to the second of the links below for more details
Expand | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||
*Confirmation request message will be sent immediately |
Expand | ||
---|---|---|
| ||
Prerequisite: you must have a valid MailUp FTP account. Please contact your sales representative or MailUp support to request one Here is how to import a list of recipients using the fileName parameter.
|
Description | Create and execute a task that imports specified recipients. Import task ID is returned | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | POST | |||||||
URL | Import recipients into a list
Import recipients into a group (a group always belongs to a single list)
| |||||||
JSON request (example) |
| |||||||
JSON response (example) | 3 (import ID, a progressive number) | |||||||
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 sentwith 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).
Code Block |
---|
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 previousstep, 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
Code Block |
---|
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 import information
As stated above, bulk import tasks are asynchronous. Since you can run only one import task a time, it is important to check if there is a running process before starting a new one.
This section contains a method to query the status of a process by specifying its ID, a method to get a list of import tasks and a method to get all the details of a completed import.
Read Import Status
Description | Read status of an import task by specifying its ID. List ID is not required. | |||||
---|---|---|---|---|---|---|
HTTP Method | GET | |||||
URL |
| |||||
JSON request (example) | none | |||||
JSON response (example) |
| |||||
Paging and filtering (example) | none |
Get import status codes
Description | Retrieve the status codes of import tasks | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL |
| |||||||
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) | None |
Get list of import tasks
Description | Retrieve the list of all the import tasks | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL |
| |||||||
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) |
|
Get import report
Description | Retrieve the import details by specifying the import ID. This method is useful when the task is completed and you need a report of how many recipients have been imported | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL |
| |||||||
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) | None |
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 |
| |||||||
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 recipients with all subscription details
Description | Retreive subscribed/unsubscribed recipients including all the available details about subscriptions and unsubscription | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
URL | For EMAIL channel:
For SMS channel:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
JSON request (example) | none | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
JSON response (example) |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Paging and filtering (examples) | 2 items per page, get first page (count starts from zero)
Retrieve the subscriber of a specified list whose Email is 'peter@example.com' filterby="Email=='peter@example.com'". Parameter names can be retreived from the response body. Please note that strict filter matching with "==" is much more performing than using "Contains" directive.
Retrieve all the subscribers of a specified list whose MobilePrefix is '0039' filterby="MobilePrefix=='0039'" and sort them by recipient identifier orderby="idRecipient asc". Parameter names can be retreived from the response body.
|
Read subscribed recipients
Description | Retreive subscribers of specified list | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL | For EMAIL channel:
For SMS channel:
| |||||||
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) | 2 items per page, get first page (count starts from zero)
Filtering by channel:
NB: remember that parameter names can be retrieved from the response body. |
Read unsubscribed recipients
As for "subscribed", but in this case the endpoint is /Console/List/{ID_LIST}/Recipients/Unsubscribed.
For EMAIL channel:
Code Block |
---|
GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Recipients/Unsubscribed |
For SMS channel:
Code Block |
---|
GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{ID_LIST}/Recipients/Unsubscribed |
Read pending recipients
As for "subscribed", but in this case the endpoint is /Console/List/{ID_LIST}/Recipients/Pending.
For EMAIL channel:
Code Block |
---|
GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Recipients/Pending |
For SMS channel:
Code Block |
---|
GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{ID_LIST}/Recipients/Pending |
Retrieve recipients by ID, email or mobile number
Description | Global search based on ID, email or mobile number | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL |
| |||||||
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) |
Retrieve recipients that belong to a group
A recipient can belong to zero, one or more groups of a list, regardless its subscription statusinthat list.
Read group members
Description | Retrieve only email subscribers that belong to specified group. Group members that are not subscribed one mail channel are not returned | ||
---|---|---|---|
HTTP Method | GET | ||
URL |
|
...
|
...
| |
JSON request (example) |
---|
...
none |
...
JSON response (example) |
|
---|
...
|
...
|
...
|
...
JSON response (example)
...
3
...
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 |
| |||||
JSON request (example) | none
| |||||
JSON response (example) |
| |||||
Paging and filtering (example) | none
|
Manage a single email recipient / subscriber
Info |
---|
Definitions:
|
Create a recipient / subscriber
A single recipient can be added to a console account by calling Import Recipients and passing its details (at least one between email and mobile number and, optionally, personal data fields) as parameter.
Code Block |
---|
POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Recipients |
You cannot create a new recipient without subscribing it
Expand | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||
|
Update personal data fields of a subscriber
This section refers to changes on personal data fields of specified recipient (that must already exist)
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 |
| ||||
JSON request (example) |
| ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none
|
Update subscription status of a recipient
You can use API to force subscription or unsubscription status of an existing recipient on a specified list. Unsubscription though REST API can be performed only in this way, since bulk unsubscription is not available yet.
Update operation requires
- Recipient ID, refer to section "Check if a subscriber exists"
- List ID
Description | Add/remove the recipient with the related id to the specified group | ||||
---|---|---|---|---|---|
HTTP Method | POST/DELETE | ||||
URL | Subscribe
Unsubscribe
| ||||
JSON request (example) | none | ||||
JSON response (example) | none | ||||
Paging and filtering (example) | none
|
Update group membership of a subscriber
You can use API to add or remove an existing recipient from a specified group.
Update operation requires
- Recipient ID, refer to section "Check if a subscriber exists"
- The Group ID
...
Description
...
Add/remove the recipient with the related id to the specified group
...
HTTP Method
...
POST/DELETE
...
URL
Add
...
| ||
Paging and filtering (example) | 2 items per page, get first page (count starts from zero)
Retreive the subscriber of a specified list whose Email is 'peter@example.com' filterby="Email=='peter@example.com'". Parameter names can be retreived from the response body.
|
---|
Manage recipient subscription status
Retrieve recipient subscription status by list
The same recipient can belong to different lists with a different subscription status. For example, imagine your account has three different lists: the same recipient belongs to the first list as subscribed, to the second one as unsubscribed and to the third one as pending.
The following method allows you to retrieve all the the list subscription statuses for the specified recipient.
Description | Retrieve the list subscription status by recipient | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | GET | ||||||||||||||||||||
URL | For EMAIL channel:
For SMS channel:
| ||||||||||||||||||||
JSON request (example) | none | ||||||||||||||||||||
JSON response (example) |
| ||||||||||||||||||||
Paging and filtering (example) | 2 items per page, get first page (count starts from zero)
|
...
Remove
...
Retrieve all the lists where the recipient is subscribed (OPTIN) filterBy="Status=='PENDING'" and sort them by Optin_Date descending orderBy="Optin_Date desc". Parameter names can be retreived from the response body. |
...
JSON request (example)
...
none
...
JSON response (example)
...
none
...
Paging and filtering (example)
...
none
Check if a subscriber exists
With this method you can also retreive recipientID and personal data fields of the recipient with the specified email
Note | ||
---|---|---|
| ||
If you are using this method to retrieve recipient ID, unfotunately there is not a method that allows you to search recipient "by email address regardless the subscription status". Hence, it is possible that you have to make up to three search: in subscribed, in unsubscribed and finally in pending recipients of that list, |
...
Description
...
Check subscriber and retreive data
...
HTTP Method
...
GET
...
|
...
|
...
see example in the "paging and filtering" row
...
JSON request (example)
...
none
...
JSON response (example)
...
Expand | |||||||
---|---|---|---|---|---|---|---|
when the specified recipient belongs to list suscribers the response contains the personal data fields of the recipient
when the specified recipient does not belong to list subscribers (i.e. it may be not existing but also unsubscribed or subscribed only to other MailUp lists for that console account) an empty list is returned
|
...
Paging and filtering (example)
...
|
Unsubscribe recipient from specified lists
This method could be very useful if you need to unsubscribe an optin recipient from multiple lists.
To perform this operation you need to specify into the body of the the array of list identifiers from which the recipient should be unsubscribed. As you can see in the box below, the response contains 2 arrays:
UnsubscribedFrom: this array contains the identifiers of the lists from which the method execution unsubscribes the recipient
NotUnsubscribedFrom: this array contains the identifiers of the lists from which the method execution does not unsubscribe the recipient, because:
- it has already unsubscribed
- it was in a PENDING status
- the recipient does not belong to this list
Description | Unsubscribe a subscribed recipient from one or more specified lists | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | DELETE | |||||||
URL | For EMAIL channel:
For SMS channel:
| |||||||
JSON request (example) |
| |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) | - |
Remove recipient
You can fully remove a recipient from a single list or from all lists. Personal data fields are kept (i.e. not deleted) until the recipient is present in at least one MailUp list, regardless its subscription status.
Description | Remove a recipient from a single list or from all lists | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | DELETE | ||||||||||||
URL |
Please note that the first endpoint uses "Recipient" (singular) while the second uses "Recipients" (plural) | ||||||||||||
JSON request (example) | none | ||||||||||||
JSON response (example) |
| ||||||||||||
Paging and filtering (example) | - |
Enable or disable tracking
Email tracking (i.e. opens and clicks) can be enabled or disabled at recipient level.
Description | Enable or disable tracking | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST | ||||||||||||
URL |
| ||||||||||||
JSON request (example) |
| ||||||||||||
JSON response (example) |
The TimeStamp field is set only when disabling tracking. If you enable it, this field is cleared | ||||||||||||
Paging and filtering (example) | - |
Read tracking status
Before changing the tracking status, you may need to check the current value
Description | Read tracking status for a recipient on a specified list | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | GET | ||||||||||||
URL |
| ||||||||||||
JSON request (example) | none | ||||||||||||
JSON response (example) |
The TimeStamp field is set only when disabling tracking. If you enable it, this field is cleared | ||||||||||||
Paging and filtering (example) | - |