This page provides you information about how to This page provides you information about how to manage recipients (subscribe, unsubscribe, update personal data).

Tip

title	New to MailUp?

Confused with MailUp terminology? Please take a moment to review the Definitions and Recipients Management sections.

On this page:

Toc

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

...

Manage a single email recipient / subscriber

Info

Definitions:

Email Recipient = in reference to a MailUp account, it's an end whose email address and optionally personal data fields is added to MailUp. A recipient may be subscribed, not subscribed, unsubscribed or pending in any of the Lists that exist in that MailUp account.
Email Subscriber = in reference to a specific list within a MailUp account, it's a recipient that is currently subscribed to that list

Add a recipient / subscriber

A single recipient can be added to a console account by calling Import Recipients and passing its details as parameters (at least one between email and mobile number and, optionally, personal data fields).

Code Block
POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console

...

JSON request (example)

...

none

...

JSON response (example)

...

This is the response when URI /Console/Recipient/DynamicFields?PageNumber=0&PageSize=30&orderby="Id+asc" is called

...

language	html/xml

...

/List/{id_List}/Recipients

You cannot create a new recipient without subscribing it.

Expand

title	Click here for more details...

Use case	Action	Description
Brand new recipient	added and subscribed	not existing in any list of that account
Recipient is already subscribed on that list	personal data fields are updated	email address and mobile number are primary keys
Recipient is already subscribed/unsubscribed on another list	subscribed to specified list, personal data fields are updated
Key mismatch	request is denied	Recipient was already present with both email address and mobile number, import operation provides the same email and a different mobile number (or viceversa)

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

Code Block
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Recipient/Detail

JSON request (example)

Expand

Modifying the "Region" field for recipient with ID = 23

Code Block
{ "Email":"test25@example.com", "Fields":[{ "Description":"Region", "Id":8, "Value":"England" }], "Name":"Test", "idRecipient":23 }

JSON response (example)

Expand

Code Block

{"IsPaginated":false,"Items":[{"Email":"test25@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":""},{"Description":"phoneLastName","Id":2,"Value":11""},{"Description":"CustomerIDCompany","Id":12}3,{"DescriptionValue":"LatestOrderID","Id":13},{"Description":"LatestOrderDateCity","Id":14}4,{"DescriptionValue":"LatestOrderAmount","Id":15},{"Description":"LatestOrderProductIDsProvince","Id":165,"Value":""},{"Description":"LatestOrderCategoryIDsZIP","Id":6,"Value":17""},{"Description":"LatestShippedOrderDateState","Id":7,"Value":18""},{"Description":"LatestShippedOrderIDRegion","Id":8,"Value":19"Italy"},{"Description":"LatestAbandonedCartDateAddress","Id":20}9,{"DescriptionValue":"LatestAbandonedCartTotal","Id":21},{"Description":"LatestAbandonedCartIDGender ","Id":22}10,{"DescriptionValue":"TotalOrdered","Id":23},{"Description":"TotalOrderedLast12mphone","Id":24}11,{"DescriptionValue":"TotalOrderedLast30d","Id":25},{"Description":"AllOrderedProductIDsCustomerID","Id":26}]12,"PageNumberValue":0""},{"PageSizeDescription":30"LatestOrderID","SkippedId":013,"TotalElementsCountValue":26}

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

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)

Expand

Code Block

language	html/xml

{"IsPaginated":false,"Items":[{"Email":"john@example.com","Fields":[{"Description":"FirstName","Id":1""},{"Description":"LatestOrderDate","Id":14,"Value":""},{"Description":"LatestOrderAmount","Id":15,"Value":""},{"Description":"LatestOrderProductIDs","Id":16,"Value":""},{"Description":"LatestOrderCategoryIDs","Id":17,"Value":""},{"Description":"LatestShippedOrderDate","Id":18,"Value":""},{"Description":"LastNameLatestShippedOrderID","Id":219,"Value":""},{"Description":"CompanyLatestAbandonedCartDate","Id":320,"Value":""},{"Description":"CityLatestAbandonedCartTotal","Id":421,"Value":""},{"Description":"ProvinceLatestAbandonedCartID","Id":522,"Value":""},{"Description":"ZIPTotalOrdered","Id":623,"Value":""},{"Description":"StateTotalOrderedLast12m","Id":724,"Value":""},{"Description":"RegionTotalOrderedLast30d","Id":825,"Value":""},{"Description":"AddressAllOrderedProductIDs","Id":926,"Value":""}],{"DescriptionMobileNumber":null,"Gender MobilePrefix":null,"IdName":10null,"ValueidRecipient":""23}],{"DescriptionPageNumber":"phone"0,"IdPageSize":1120,"ValueSkipped":""}0,{"Description":"CustomerID","Id":12,"Value":""},{"Description":"LatestOrderID","Id":13,"Value":""},{"Description":"LatestOrderDate","Id":14,"Value":""},{"Description":"LatestOrderAmount","Id":15,"Value":""},{"Description":"LatestOrderProductIDs","Id":16,"Value":""},{"Description":"LatestOrderCategoryIDs","Id":17,"Value":""},{"Description":"LatestShippedOrderDate","Id":18,"Value":""},{"Description":"LatestShippedOrderID","Id":19,"Value":""},{"Description":"LatestAbandonedCartDate","Id":20,"Value":""},{"Description":"LatestAbandonedCartTotal","Id":21,"Value":""},{"Description":"LatestAbandonedCartID","Id":22,"Value":""},{"Description":"TotalOrdered","Id":23,"Value":""},{"Description":"TotalOrderedLast12m","Id":24,"Value":""},{"Description":"TotalOrderedLast30d","Id":25,"Value":""},{"Description":"AllOrderedProductIDs","Id":26,"Value":""}],"MobileNumber":null,"MobilePrefix":null,"Name":null,"idRecipient":16},{"Email":"mary@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":""},{"Description":"LastName","Id":2,"Value":""},{"Description":"Company","Id":3,"Value":""},{"Description":"City","Id":4TotalElementsCount":1}

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

Note
POST operation described in this section enables you to force subscription of unsubscribed recipients regardless the unsubscription reason. It is recommendend that you use this feature only if you're aware of its effects.

Description

Add/remove the recipient with the related id to the specified group

HTTP Method

POST/DELETE

URL

Subscribe

Code Block
POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Subscribe/{id_Recipient}

Unsubscribe

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

Code Block
POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{id_Group}/Subscribe/{id_Recipient}

Remove

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

Note

title	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

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Recipients/Subscribed?filterby="Email.Contains('{Email}')"

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

Code Block

language	html/xml

{"IsPaginated":false,"Items":[{"Email":"peter@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":""},{"Description":"ProvinceLastName","Id":52,"Value":""},{"Description":"ZIPCompany","Id":63,"Value":""},{"Description":"StateCity","Id":74,"Value":""},{"Description":"RegionProvince","Id":85,"Value":""},{"Description":"AddressZIP","Id":96,"Value":""},{"Description":"Gender State","Id":107,"Value":""},{"Description":"phoneRegion","Id":118,"Value":""},{"Description":"Address","Id":9,"Value":""},{"Description":"Gender ","Id":10,"Value":""},{"Description":"phone","Id":11,"Value":""},{"Description":"CustomerID","Id":12,"Value":""},{"Description":"LatestOrderID","Id":13,"Value":""},{"Description":"LatestOrderDate","Id":14,"Value":""},{"Description":"LatestOrderAmount","Id":15,"Value":""},{"Description":"LatestOrderProductIDs","Id":16,"Value":""},{"Description":"LatestOrderCategoryIDs","Id":17,"Value":""},{"Description":"LatestShippedOrderDate","Id":18,"Value":""},{"Description":"LatestShippedOrderID","Id":19,"Value":""},{"Description":"LatestAbandonedCartDate","Id":20,"Value":""},{"Description":"LatestAbandonedCartTotal","Id":21,"Value":""},{"Description":"LatestAbandonedCartID","Id":22,"Value":""},{"Description":"TotalOrdered","Id":23,"Value":""},{"Description":"TotalOrderedLast12m","Id":24,"Value":""},{"Description":"TotalOrderedLast30d","Id":25,"Value":""},{"Description":"AllOrderedProductIDs","Id":26,"Value":""}],"MobileNumber":null,"MobilePrefix":null,"Name":null,"idRecipient":1513}],{"EmailPageNumber":"susan@example.com"0,"FieldsPageSize":[{20,"DescriptionSkipped":"FirstName"0,"Id":1,"Value":"Susan"},{"Description":"LastName","Id":2,"Value":"Smith"},{"Description":"Company","Id":3,"Value":"ACME"},{"Description":"City","Id":4,"Value":"Milan"},{"Description":"Province","Id":5,"Value":"MI"},{"Description":"ZIP","Id":6,"Value":"20100"},{"Description":"State","Id":7,"Value":"Italy"},{"Description":"Region","Id":8,"Value":""},{"Description":"Address","Id":9,"Value":""},{"Description":"Gender ","Id":10,"Value":"male"},{"Description":"phone","Id":11,"Value":"1234567"},{"Description":"CustomerID","Id":12,"Value":"1"},{"Description":"LatestOrderID","Id":13,"Value":"6"},{"Description":"LatestOrderDate","Id":14,"Value":"1397470773TotalElementsCount":1}

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

Code Block
{"IsPaginated":false,"Items":[],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":0}

Paging and filtering (example)

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/3/Recipients/Subscribed?filterby="Email.Contains(%27peter@example.com%27)"

...

Add recipients (asynchronous import)

Asynchronous import is used either for adding a single recipient to MailUp or to perform a bulk import. 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.

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.

Import recipients

LatestOrderAmount151000LatestOrderProductIDs161LatestOrderCategoryIDs171LatestShippedOrderDate181397470973{DescriptionLatestShippedOrderIDId19Value6DescriptionLatestAbandonedCartDateId20,"Value":"1397468462"},LatestAbandonedCartTotal21200"Description":"LatestAbandonedCartID",221"Description":"TotalOrdered",231200{"Description":"TotalOrderedLast12m","Id":24,"Value1200,{"Description":"TotalOrderedLast30d","Id":25,"Value":"1200"},{"Description":"AllOrderedProductIDs","Id":26,"Value":"1,2"}],"MobileNumber":"","MobilePrefix":"","Name":"Test","idRecipient":14},{"Email":"peter@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":""},{"Description":"LastName","Id":2,"Value":""},{"Description":"Company","Id":3,"Value":""

Description

Create and execute a task that imports specified recipients. Import task ID is returned

Expand

title	Click here to see how already existing recipients are managed ...

Brand new recipents are added and subscribed to the list
Recipents that exist on other lists are subscribed to the list
Already subscribed recipents remain subscribed
Previously unsubscribed or pending recipients are updated but their subscription status does not change
If the recipient alrady exists it is updated if specified personal data are different from the specified ones. Empty fields are managed as "do not change"
Please refer to management of single recipient if you want to access to more advanced features like forcing subscription/unsubsubscription or if you want to clear a personal data field

HTTP Method

POST

URL

Import recipients into a list

Code Block
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)

Code Block
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{ID_GROUP}/Recipients

JSON request (example)

Expand

The example below imports two recipients. The first is subscribed to both email and SMS (Mobile) channels, while the second is subscribed only to email channel. For each recipient to be imported you may specify a different set of "Fields" values in a random order. Please note that field "description" field is optional. In this example the default values for English version are used, therefore names in your console account can be different than what you see below. "Name" field is mandatory but it is not accessible with MailUp console account (you can leave it empty)

Code Block

language	html/xml

[{"Email":"john@doe.uk","Fields":[{"Description":"FirstName","Id":1,"Value":"John"},{"Description":"

Province","Id":

5,"Value":"

East Midlands"},{"Description":"

LastName","Id":

2,"Value":"

Doe"},{"Description":"

TotalOrdered","Id":

23,"Value":"

2000"},{"Description":"

Company","Id":

3,"Value":"

Main Ltd"}],

MobileNumber":"

9874561153","

MobilePrefix":

"0044","

Name":"

"},{"

Email":"

mary@poppins.uk","

Fields":

[{"Description":"

FirstName","Id":

1,"Value":"

Mary"},{

"Id":

3,"Value":"

Baby sitter"},{

"Id":

4,"Value":"

London"}],

"Name":"

"}

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

Code Block
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Import/{IMPORT_ID}

JSON request (example)

none

JSON response (example)

Code Block

language	html/xml

{"Completed":true,"CreatedRecipients":1,"ImportedRecipients":0,"NotValidRecipients":0,"UpdatedRecipients":0,"ValidRecipients":1,"idImport":3}

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

Code Block
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Recipient/DynamicFields

JSON request (example)

none

JSON response (example)

Expand

This is the response when URI /Console/Recipient/DynamicFields?PageNumber=0&PageSize=30&orderby="Id+asc" is called

Code Block

language	html/xml

{"IsPaginated":false,"Items":[{"Description":"FirstName","Id":1},{"Description":"LastName","Id":2},{"Description":"CityCompany","Id":43},{"ValueDescription":"City","Id":4},{"Description":"Province","Id":5,"Value":""},{"Description":"ZIP","Id":6,"Value":""},{"Description":"State","Id":7,"Value":""},{"Description":"Region","Id":8,"Value":""},{"Description":"Address","Id":9,"Value":""},{"Description":"Gender ","Id":10,"Value":""},{"Description":"phone","Id":11,"Value":""},{"Description":"CustomerID","Id":12,"Value":""},{"Description":"LatestOrderID","Id":13,"Value":""},{"Description":"LatestOrderDate","Id":14},{"ValueDescription":"LatestOrderAmount"},{"Description":"LatestOrderAmount","Id":15,"Value":""},{"Description":"LatestOrderProductIDs","Id":16,"Value":""},{"Description":"LatestOrderCategoryIDs","Id":17,"Value":""},{"Description":"LatestShippedOrderDate","Id":18,"Value":""},{"Description":"LatestShippedOrderID","Id":19,"Value":""},{"Description":"LatestAbandonedCartDate","Id":20,"Value":""},{"Description":"LatestAbandonedCartTotal","Id":21,"Value":""},{"Description":"LatestAbandonedCartID","Id":22,"Value":""},{"Description":"TotalOrdered","Id":23,"Value":""},{"Description":"TotalOrderedLast12m","Id":24,"Value":""},{"Description":"TotalOrderedLast30d","Id":25,"Value":""},{"Description":"AllOrderedProductIDs","Id":26}],"ValuePageNumber":0,"PageSize"}],"MobileNumber":null,"MobilePrefix":null,"Name":null,"idRecipient":13}],"PageNumber":0,"PageSize":20:30,"Skipped":0,"TotalElementsCount":426}

Paging and filtering (example)

2 items per page, get first page (count starts from zero)

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc

Use endpoint /Console/

List/1/Recipients/Subscribed

Recipient/DynamicFields?PageNumber=0&PageSize

=2

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

=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

1?filterby="Email.Contains(%27example%27)"&orderby="Email+asc"

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

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

{"IsPaginated":false,"Items":[{"Email":"peter@example.com","Fields":[{"Description":"FirstName","Id":1

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

Code Block
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{id_Group}/Recipients

JSON request (example)

none

JSON response (example)

Expand

Code Block

language	html/xml

JSON request (example)

none

JSON response (example)

Expand

Code Block

language	html/xml

{"IsPaginated":false,"Items":[{"Email":"john@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":""},{"Description":"LastName","Id":2,"Value":""},{"Description":"Company","Id":3,"Value":""},{"Description":"City","Id":4,"Value":""},{"Description":"Province","Id":5,"Value":""},{"Description":"ZIP","Id":6,"Value":""},{"Description":"State","Id":7,"Value":""},{"Description":"Region","Id":8,"Value":""},{"Description":"Address","Id":9,"Value":""},{"Description":"LastNameGender ","Id":210,"Value":""},{"Description":"Companyphone","Id":311,"Value":""},{"Description":"CityCustomerID","Id":412,"Value":""},{"Description":"ProvinceLatestOrderID","Id":513,"Value":""},{"Description":"ZIPLatestOrderDate","Id":614,"Value":""},{"Description":"StateLatestOrderAmount","Id":715,"Value":""},{"Description":"RegionLatestOrderProductIDs","Id":816,"Value":""},{"Description":"AddressLatestOrderCategoryIDs","Id":917,"Value":""},{"Description":"Gender LatestShippedOrderDate","Id":1018,"Value":""},{"Description":"phoneLatestShippedOrderID","Id":1119,"Value":""},{"Description":"CustomerIDLatestAbandonedCartDate","Id":1220,"Value":""},{"Description":"LatestOrderIDLatestAbandonedCartTotal","Id":1321,"Value":""},{"Description":"LatestOrderDateLatestAbandonedCartID","Id":1422,"Value":""},{"Description":"LatestOrderAmountTotalOrdered","Id":1523,"Value":""},{"Description":"LatestOrderProductIDsTotalOrderedLast12m","Id":1624,"Value":""},{"Description":"LatestOrderCategoryIDsTotalOrderedLast30d","Id":1725,"Value":""},{"Description":"LatestShippedOrderDateAllOrderedProductIDs","Id":1826,"Value":""}],{"DescriptionMobileNumber":"LatestShippedOrderID"null,"MobilePrefix":null,"Name":null,"IdidRecipient":1916},{"ValueEmail":"mary@example.com"},"Fields":[{"Description":"LatestAbandonedCartDateFirstName","Id":201,"Value":""},{"Description":"LatestAbandonedCartTotalLastName","Id":212,"Value":""},{"Description":"LatestAbandonedCartIDCompany","Id":223,"Value":""},{"Description":"TotalOrderedCity","Id":234,"Value":""},{"Description":"TotalOrderedLast12mProvince","Id":245,"Value":""},{"Description":"TotalOrderedLast30dZIP","Id":256,"Value":""},{"Description":"AllOrderedProductIDsState","Id":267,"Value":""}],{"MobileNumberDescription":null"Region","MobilePrefixId":null8,"NameValue":null,"idRecipient":13}],{"PageNumberDescription":0"Address","PageSizeId":209,"SkippedValue":0""},{"TotalElementsCount":1}

Paging and filtering (example)

2 items per page, get first page (count starts from zero)

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/27/Recipients?PageNumber=0&PageSize=2

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/Group/27/Recipients?filterby="Email.Contains(%27example%27)"&orderby="Email+asc"

Add recipients (asynchronous import)

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 to support an upload size that is about 7MB for each call. This limit approximately corresponds to 5000 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.

Import recipients

The example below imports two recipients. The first is subscribed to both email and SMS (Mobile) channels, while the second is subscribed only to email channel. For each recipient to be imported you may specify a different set of "Fields" values in a random order. Please note that field "description" field is optional. In this example the default values for English version are used, therefore names in your console account can be different than what you see below. "Name" field is mandatory but it is not accessible with MailUp console account (you can leave it empty)

[{"Email":"john@doe.uk","Fields":[{"Description":"FirstName","Id":1,"Value":"JohnProvince5East MidlandsLastName2DoeTotalOrdered232000Company3Main Ltd]MobileNumber9874561153MobilePrefix"0044"NameEmail"mary@poppins.uk"Fields[FirstName1MaryId3,"Value":"Baby sitter"},{4London]Name"}]

Description

Create and execute a task that imports specified recipients. Import task ID is returned

Expand

title	Click here to see how already existing recipients are managed ...

Brand new recipents are added and subscribed to the list
Recipents that exist on other lists are subscribed to the list
Already subscribed recipents remain subscribed
Previously unsubscribed or pending recipients are updated but their subscription status does not change
If the recipient alrady exists it is updated if specified personal data are different from the specified ones. Empty fields are managed as "do not change"
Please refer to management of single recipient if you want to access to more advanced features like forcing subscription/unsubsubscription or if you want to clear a personal data field

HTTP Method

POST

URL

Import recipients into a list

Code Block
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)

Code Block
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{ID_GROUP}/Recipients

JSON request (example)

Expand

Code Block

language	html/xml

Description":"Gender ","Id":10,"Value":""},{"Description":"phone","Id":11,"Value":""},{"Description":"CustomerID","Id":12,"Value":""},{"Description":"LatestOrderID","Id":13,"Value":""},{"Description":"LatestOrderDate","Id":14,"Value":""},{"Description":"LatestOrderAmount","Id":15,"Value":""},{"Description":"LatestOrderProductIDs","Id":16,"Value":""},{"Description":"LatestOrderCategoryIDs","Id":17,"Value":""},{"Description":"LatestShippedOrderDate","Id":18,"Value":""},{"Description":"LatestShippedOrderID","Id":19,"Value":""},{"Description":"LatestAbandonedCartDate","Id":20,"Value":""},{"Description":"LatestAbandonedCartTotal","Id":21,"Value":""},{"Description":"LatestAbandonedCartID","Id":22,"Value":""},{"Description":"TotalOrdered","Id":23,"Value":""},{"Description":"TotalOrderedLast12m","Id":24,"Value":""},{"Description":"TotalOrderedLast30d","Id":25,"Value":""},{"Description":"AllOrderedProductIDs","Id":26,"Value":""}],"MobileNumber":null,"MobilePrefix":null,"Name":null,"idRecipient":15},{"Email":"susan@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":"Susan"},{"Description":"LastName","Id":2,"Value":"Smith"},{"Description":"Company","Id":3,"Value":"ACME"},{"Description":"City","Id":4,"Value":"Milan"},{"Description":"Province","Id":5,"Value":"MI"},{"Description":"

ZIP","Id":

6,"Value":"

20100"},{"Description":"

State","Id":

7,"Value":"

Italy"},{"Description":"

Region","Id":

8,"Value":"

"},{"Description":"

Address","Id":

9,"Value":"

"}

,{"

Description":"

Gender ","

Id":

10,"

Value":"male"},{"

Description":

"phone","Id":11,"

Value":

"1234567"},{"Description":"

CustomerID","Id":

12,"Value":"

1"},{"

Description":

"LatestOrderID","Id":

13,"Value":"

6"}

,{"

Description":"LatestOrderDate","

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

Code Block
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Import/{IMPORT_ID}

JSON request (example)

none

JSON response (example)

Code Block

language	html/xml

{"Completed":true,"CreatedRecipients":1,"ImportedRecipients":0,"NotValidRecipients":0,"UpdatedRecipients":0,"ValidRecipients":1,"idImport":3}

Paging and filtering (example)

none

Manage a single email recipient / subscriber

Info

Definitions:

Email Recipient = with reference to a MailUp console account, it's an end user whose email address and optionally personal data fields is added to MailUp. A recipient may be subscribed, not subscribed, unsubscribed or pending on MailUp lists
Email Subscriber = with reference to a specific MailUp list, it's a recipient that is currently subscribed to that list

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

title	Click here for more details...

Use case	Action	Description
Brand new recipient	added and subscribed	not existing in any list of that account
Recipient is already subscribed on that list	personal data fields are updated	email address and mobile number are primary keys
Recipient is already subscribed/unsubscribed on another list	subscribed to specified list, personal data fields are updated
Key mismatch	request is denied	Recipient was already present with both email address and mobile number, import operation provides the same email and a different mobile number (or viceversa)

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

Code Block
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Recipient/Detail

JSON request (example)

Expand

Modifying the "Region" field for recipient with ID = 23

Code Block
{ "Email":"test25@example.com", "Fields":[{ "Description":"Region", "Id":8, "Value":"England" }], "Name":"Test", "idRecipient":23 }

JSON response (example)

Expand

Code Block

{"IsPaginated":false,"Items":[{"Email":"test25@exampleId":14,"Value":"1397470773"},{"Description":"LatestOrderAmount","Id":15,"Value":"1000"},{"Description":"LatestOrderProductIDs","Id":16,"Value":"1"},{"Description":"LatestOrderCategoryIDs","Id":17,"Value":"1"},{"Description":"LatestShippedOrderDate","Id":18,"Value":"1397470973"},{"Description":"LatestShippedOrderID","Id":19,"Value":"6"},{"Description":"LatestAbandonedCartDate","Id":20,"Value":"1397468462"},{"Description":"LatestAbandonedCartTotal","Id":21,"Value":"200"},{"Description":"LatestAbandonedCartID","Id":22,"Value":"1"},{"Description":"TotalOrdered","Id":23,"Value":"1200"},{"Description":"TotalOrderedLast12m","Id":24,"Value":"1200"},{"Description":"TotalOrderedLast30d","Id":25,"Value":"1200"},{"Description":"AllOrderedProductIDs","Id":26,"Value":"1,2"}],"MobileNumber":"","MobilePrefix":"","Name":"Test","idRecipient":14},{"Email":"peter@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":""},{"Description":"LastName","Id":2,"Value":""},{"Description":"Company","Id":3,"Value":""},{"Description":"City","Id":4,"Value":""},{"Description":"Province","Id":5,"Value":""},{"Description":"ZIP","Id":6,"Value":""},{"Description":"State","Id":7,"Value":""},{"Description":"Region","Id":8,"Value":"Italy"},{"Description":"Address","Id":9,"Value":""},{"Description":"Gender ","Id":10,"Value":""},{"Description":"phone","Id":11,"Value":""},{"Description":"CustomerID","Id":12,"Value":""},{"Description":"LatestOrderID","Id":13,"Value":""},{"Description":"LatestOrderDate","Id":14,"Value":""},{"Description":"LatestOrderAmount","Id":15,"Value":""},{"Description":"LatestOrderProductIDs","Id":16,"Value":""},{"Description":"LatestOrderCategoryIDs","Id":17,"Value":""},{"Description":"LatestShippedOrderDate","Id":18,"Value":""},{"Description":"LatestShippedOrderID","Id":19,"Value":""},{"Description":"LatestAbandonedCartDate","Id":20,"Value":""},{"Description":"LatestAbandonedCartTotal","Id":21,"Value":""},{"Description":"LatestAbandonedCartID","Id":22,"Value":""},{"Description":"TotalOrdered","Id":23,"Value":""},{"Description":"TotalOrderedLast12m","Id":24,"Value":""},{"Description":"TotalOrderedLast30d","Id":25,"Value":""},{"Description":"AllOrderedProductIDs","Id":26,"Value":""}],"MobileNumber":null,"MobilePrefixId":null23,"NameValue":null,"idRecipient":23}],{"PageNumberDescription":0"TotalOrderedLast12m","PageSizeId":2024,"SkippedValue":0""},{"TotalElementsCount":1}

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

Note
POST operation described in this section enables you to force subscription of unsubscribed recipients regardless the unsubscription reason. It is recommendend that you use this feature only if you're aware of its effects.

Subscribe

URL
Description	Add/remove the recipient with the related id to the specified group
HTTP Method	POST/DELETE

Code Block
POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Subscribe/{id_Recipient}

Unsubscribe

Code BlockDELETE

Description":"TotalOrderedLast30d","Id":25,"Value":""},{"Description":"AllOrderedProductIDs","Id":26,"Value":""}],"MobileNumber":null,"MobilePrefix":null,"Name":null,"idRecipient":13}],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":4}

Paging and filtering (example)

2 items per page, get first page (count starts from zero)

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 membership of a subscriber

You can use API to add or remove an existing recipient from a specified group. Removing a recipient from a group does not affect the list subscription status.

Update operation requires

Recipient ID, refer to section "Check if a subscriber exists"
The Group ID

Add

POST

URL
Description	Add/remove the recipient with the related id to the specified group
HTTP Method	POST/DELETE
Code Block
1/Recipients/Subscribed?PageNumber=0&PageSize=2 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}/

...

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

title	Known restriction

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

...

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

Paging and filtering (example)

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

Code Block
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/

List

Group/{id_

List

Group}/Recipients

/Subscribed?filterby="Email.Contains('{Email}')"see example in the "paging and filtering" row

JSON request (example)

none

JSON response (example)

when the specified recipient belongs to list suscribers the response contains the personal data fields of the recipient

Expand

Code Block

language	html/xml

{"IsPaginated":false,"Items":[{"Email":"peter@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":""},{"Description":"LastName","Id":2,"Value":""},{"Description":"Company","Id":3,"Value":""},{"Description":"City","Id":4,"Value":""},{"Description":"Province","Id":5,"Value":""},{"Description":"ZIP","Id":6,"Value":""},{"Description":"State","Id":7,"Value":""},{"Description":"Region","Id":8,"Value":""},{"Description":"Address","Id":9,"Value":""},{"Description":"Gender ","Id":10,"Value":""},{"Description":"phone","Id":11,"Value":""},{"Description":"CustomerID","Id":12,"Value":""},{"Description":"LatestOrderID","Id":13,"Value":""},{"Description":"LatestOrderDate","Id":14,"Value":""},{"Description":"LatestOrderAmount","Id":15,"Value":""},{"Description":"LatestOrderProductIDs","Id":16,"Value":""},{"Description":"LatestOrderCategoryIDs","Id":17,"Value":""},{"Description":"LatestShippedOrderDate","Id":18,"Value":""},{"Description":"LatestShippedOrderID","Id":19,"Value":""},{"Description":"LatestAbandonedCartDate","Id":20,"Value":""},{"Description":"LatestAbandonedCartTotal","Id":21,"Value":""},{"Description":"LatestAbandonedCartID","Id":22,"Value":""},{"Description":"TotalOrdered","Id":23,"Value":""},{"Description":"TotalOrderedLast12m","Id":24,"Value":""},{"Description":"TotalOrderedLast30d","Id":25,"Value":""},{"Description":"AllOrderedProductIDs","Id":26,"Value":""}],"MobileNumber":null,"MobilePrefix":null,"Name":null,"idRecipient":13}],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":1}

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

Code Block
{"IsPaginated":false,"Items":[],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":0}

,"idRecipient":13}],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":1}

Paging and filtering (example)

2 items per page, get first page (count starts from zero)

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/27/Recipients?PageNumber=0&PageSize=2

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

Group/

3

27/Recipients

/Subscribed

?filterby="Email.Contains(

%27peter@example.com%27)"

%27example%27)"&orderby="Email+asc"

Versions Compared

Old Version 32

New Version 33

Key

Read personal data fields configuration

Manage a single email recipient / subscriber

Add a recipient / subscriber

Update personal data fields of a subscriber

Retrieve all subscribed/unsubscribed/pending recipients from a list

Read subscribed recipients on Email channel

Update subscription status of a recipient

Update group assignment

Check if a subscriber exists

Add recipients (asynchronous import)

Import recipients

Read Import Status

Read personal data fields configuration

Retrieve all subscribed/unsubscribed/pending recipients from a list

Read subscribed recipients on Email channel

Read unsubscribed recipients on Email channel

Read pending recipients on Email channel

Retrieve recipients that belong to a group

Read group members

Add recipients (asynchronous import)

Import recipients

Read Import Status

Manage a single email recipient / subscriber

Create a recipient / subscriber

Update personal data fields of a subscriber

Update subscription status of a recipient

Update group membership of a subscriber

Read unsubscribed recipients on Email channel

Check if a subscriber exists

Read pending recipients on Email channel

Retrieve recipients that belong to a group

Read group members

Page Comparison

Versions Compared

Old Version 32

New Version 33

Key

Read personal data fields configuration

Manage a single email recipient / subscriber

Add a recipient / subscriber

Update personal data fields of a subscriber

Retrieve all subscribed/unsubscribed/pending recipients from a list

Read subscribed recipients on Email channel

Update subscription status of a recipient

Update group assignment

Check if a subscriber exists

Add recipients (asynchronous import)

Import recipients

Read Import Status

Read personal data fields configuration

Retrieve all subscribed/unsubscribed/pending recipients from a list

Read subscribed recipients on Email channel

Read unsubscribed recipients on Email channel

Read pending recipients on Email channel

Retrieve recipients that belong to a group

Read group members

Add recipients (asynchronous import)

Import recipients

Read Import Status

Manage a single email recipient / subscriber

Create a recipient / subscriber

Update personal data fields of a subscriber

Update subscription status of a recipient

Update group membership of a subscriber

Read unsubscribed recipients on Email channel

Check if a subscriber exists

Read pending recipients on Email channel

Retrieve recipients that belong to a group

Read group members