Page Comparison

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

...

Info

Definitions and important notes:

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
Subscription management is list specific (i.e. subscribe/unsubscribe actions are not multi-list by default). To subscribe/unsubscribe to more lists you have to perform one subscribe/unsubscribe action on each involved list
COI (Confirmed Optin) applies on subscription process only when explicitly specified by means of "ConfirmEmail" parameter. When COI is enabled, content of the email message to be sent as "confirmation request" can be found and customized in the list settings of MailUp admin console account.

...

Manage a single email recipient / subscriber

Add a single recipient / subscriber (synchronous import)

...

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":"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,"MobilePrefix":null,"Name":null,"idRecipient":23}],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":1}

Paging and filtering (example)

none

...

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

...

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

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":"Company","Id":3},{"Description":"City","Id":4},{"Description":"Province","Id":5},{"Description":"ZIP","Id":6},{"Description":"State","Id":7},{"Description":"Region","Id":8},{"Description":"Address","Id":9},{"Description":"Gender ","Id":10},{"Description":"phone","Id":11},{"Description":"CustomerID","Id":12},{"Description":"LatestOrderID","Id":13},{"Description":"LatestOrderDate","Id":14},{"Description":"LatestOrderAmount","Id":15},{"Description":"LatestOrderProductIDs","Id":16},{"Description":"LatestOrderCategoryIDs","Id":17},{"Description":"LatestShippedOrderDate","Id":18},{"Description":"LatestShippedOrderID","Id":19},{"Description":"LatestAbandonedCartDate","Id":20},{"Description":"LatestAbandonedCartTotal","Id":21},{"Description":"LatestAbandonedCartID","Id":22},{"Description":"TotalOrdered","Id":23},{"Description":"TotalOrderedLast12m","Id":24},{"Description":"TotalOrderedLast30d","Id":25},{"Description":"AllOrderedProductIDs","Id":26}],"PageNumber":0,"PageSize":30,"Skipped":0,"TotalElementsCount":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,"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":16},{"Email":"mary@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":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","Id":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":""},{"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":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/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}/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

...

Versions Compared

Old Version 37

New Version 38

Key

Manage a single email recipient / subscriber

Add a single recipient / subscriber (synchronous import)

Check if a subscriber exists

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