Versions Compared

Old Version 35

changes.mady.by.user Massimo Arrigoni

Saved on

compared with

New Version 36

changes.mady.by.user MailUp Dev Team

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Tip
titleNew to MailUp?

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

On this page:

Toc

 

...

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 single recipient / subscriber (synchronous import)

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/List/{id_List}/Recipients

 

You cannot create a new recipient without subscribing it.

...

titleClick here for more details...

...

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. Based on the existing status, if available, and the ConfirmEmail parameter, the following scenarios hold true:

Use caseConfirmEmailActionDescription
NEW - Brand new recipient for specified list*falseadded and subscribednot existing in any list of that account

...

NEW - Brand new recipient for specified list*trueadded as "pending", request confirmation email is sentrecipient becomes "subscribed" after clicking on confirmation link received by email
OPTIN - Recipient is already subscribed on that list

...

falseno change on subscription status (subscribed) 
OPTIN - Recipient is already subscribed

...

on

...

that listtrue

...

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
{"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":"Italyno change on subscription status (subscribed)

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
 
PENDING - Recipient is already present as pending on specified listfalseno change on subscription status (pending) 
PENDING - Recipient is already present as pending on specified listtrueremains pending, confirmation request email is sentrecipient becomes "subscribed" after clicking on confirmation link received by email
OPTOUT- Recipient is already present as unsubscribed on specified listfalseno change on subscription status (unsubscribed) 
OPTOUT- Recipient is already present as unsubscribed on specified listtruemoved to pending status, confirmation request email is sentrecipient becomes "subscribed" after clicking on confirmation link received by email

*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 case the 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:

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

If you add a recipient to a group, automatically it will be added to the list related to that group.

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

 

To enable Confirmed Opt-In (COI) the querystring parameter "ConfirmEmail" must be set as true

Code Block
POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Recipient?ConfirmEmail=true
POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{id_Group}/Recipient?ConfirmEmail=true

JSON request (example)

Expand

Email is mandatory, mobile number is optional. Personal data fields are updated in any case, regardless the previous subscription status (if any).

Code Block
{
	"Fields":[{
		"Description":"name",
		"Id":1,
		"Value":"test"
	}],
	"Name":"String content",
	"Email":"test@example.com",
	"MobileNumber":"",
	"MobilePrefix":""
}

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

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":"AddressLastName","Id":92,"Value":""},{"Description":"Gender Company","Id":103,"Value":""},{"Description":"phoneCity","Id":114,"Value":""},{"Description":"CustomerIDProvince","Id":125,"Value":""},{"Description":"LatestOrderIDZIP","Id":136,"Value":""},{"Description":"LatestOrderDateState","Id":147,"Value":""},{"Description":"LatestOrderAmountRegion","Id":158,"Value":"Italy"},{"Description":"LatestOrderProductIDsAddress","Id":169,"Value":""},{"Description":"LatestOrderCategoryIDsGender ","Id":1710,"Value":""},{"Description":"LatestShippedOrderDatephone","Id":1811,"Value":""},{"Description":"LatestShippedOrderIDCustomerID","Id":1912,"Value":""},{"Description":"LatestAbandonedCartDateLatestOrderID","Id":2013,"Value":""},{"Description":"LatestAbandonedCartTotalLatestOrderDate","Id":2114,"Value":""},{"Description":"LatestAbandonedCartIDLatestOrderAmount","Id":2215,"Value":""},{"Description":"TotalOrderedLatestOrderProductIDs","Id":2316,"Value":""},{"Description":"TotalOrderedLast12mLatestOrderCategoryIDs","Id":2417,"Value":""},{"Description":"TotalOrderedLast30dLatestShippedOrderDate","Id":2518,"Value":""},{"Description":"AllOrderedProductIDsLatestShippedOrderID","Id":2619,"Value":""}],{"MobileNumberDescription":null"LatestAbandonedCartDate","MobilePrefixId":null20,"NameValue":null""},{"idRecipientDescription":23}]"LatestAbandonedCartTotal","PageNumberId":021,"PageSizeValue":20""},{"SkippedDescription":0"LatestAbandonedCartID","TotalElementsCountId":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

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

 

Update

...

subscription status of a recipient

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 statuschange 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 (see refer to section "Check if a subscriber exists")
  • Group List ID

...

Description

...

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

AddSubscribe

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

 

RemoveUnsubscribe

Code Block
DELETE https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/GroupList/{id_GroupList}/Unsubscribe/{id_Recipient}

JSON request (example)

none

JSON response (example)

none

Paging and filtering (example)

Description

Check subscriber and retreive data

HTTP Method

GET

URL

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

 

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

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

{"IsPaginated":false,"Items":[{"Email":"peter@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":""},{"Description":"LastName","Id":2,"Value":""},{"Description":"Company","Id":3

Description

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

HTTP Method

POST/DELETE

URL

JSON response (example)

Expand
Code Block
languagehtml/xml

Add

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

 

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
titleKnown 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
languagehtml/xml
{"IsPaginated":false,"Items":[{"Email":"peter@example.com","Fields":[{"Description":"FirstName","Id":1,"Value":""},{"Description":"CityLastName","Id":42,"Value":""},{"Description":"ProvinceCompany","Id":53,"Value":""},{"Description":"ZIPCity","Id":64,"Value":""},{"Description":"StateProvince","Id":75,"Value":""},{"Description":"RegionZIP","Id":86,"Value":""},{"Description":"AddressState","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}

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


...

Manage Multiple recipients 

If you need to add many recipients it is strongly recommended to use an asynchronous method instead of calling many times the single import method. Also COI option is availble for multiple recipients, in this case more method calls are required


Add recipients (asynchronous import)

Asynchronous import is used either for adding a single recipient to MailUp or to perform a bulk importto perform a bulk import of several recipients into the MailUp account. Since the process is not synchronous, it is fast, but not real time. Please check the import status in order to know whether the import task has been completed.   

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

Description

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

Expand
titleClick 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
languagehtml/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

...

 

The import process is able to recognize existing recipients (using the email address or the mobile number as unique identifiers), and update them according to the given input details. It is possible to add some querystring parameters to specify some advanced behavior for the import process:

  • ConfirmEmail=true: if specified, sets the new recipients status to "Pending", and a confirmation email is generated (but not yet sent). Please check below in the section "Send Confirmation Email" the procedure to actually send the emails generated so far.
  • importType='asOptout': if specified, the given recipients' status is set to "Optout", except for the ones already in “Pending” Status. A complete explanation of the available scenarios is provided below.
 New RecipientsPreviously SubscribedPreviously PendingPreviously unsubscribed
POST /Console/List/{id_List}/Recipients
Subscribedno changeno changeno change
POST /Console/List/{id_List}/Recipients?ConfirmEmail=true
Pending, confirmation request is added to queue*Pending, confirmation request is is added to queue*no changeno change
POST /Console/List/{id_List}/Recipients?importType=asOptout
UnsubscribedUnsubscribedno changeno change

*Confirmation request message is prepared (i.e. queued) but not automatically sent. See below (Send Confirmation Email) how to send a queued message

 

Description

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

Expand
titleClick 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
languagehtml/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
languagehtml/xml
{"Completed":true,"CreatedRecipients":1,"ImportedRecipients":0,"NotValidRecipients":0,"UpdatedRecipients":0,"ValidRecipients":1,"idImport":3}

Paging and filtering (example)

none

 

 

Send Confirmation Email

The confirmation emails (generated in the bulk import process as the result of "ConfirmEmail=true" querystring parameter) can be sent with the following process;

  •  Retrieve the SendingID of that confirmation email, with the following call, where {id_import} is the result of the current import call.  The result of this GET call is a structure with the SendingID (idImport) and the number of generated emails (EnqueuedEmails).
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 previous step, with no body. Moreover a body like  {Date:'yyyy-MM-dd HH:mm'} is required: for the "Deferred" case. NOTE: the specified date must be in UTC and at least 5 minutes in the future, with the format described in the section 'Type and cast definition' of this page: /wiki/spaces/mailupapi/pages/36340525
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_

...

JSON request (example)

...

none

 

...

JSON response (example)

...

Code Block
languagehtml/xml
{"Completed":true,"CreatedRecipients":1,"ImportedRecipients":0,"NotValidRecipients":0,"UpdatedRecipients":0,"ValidRecipients":1,"idImport":3}

...

Paging and filtering (example)

...

sending}/Deferred

 

 

...

 

Read personal data fields configuration

Any update of recipients' personal data fields requires the IDs of the fields to be updated. Resource /Console/Recipient/DynamicFields allows you to retrieve personal data fields settings for a specific MailUp account (number of fields, names and IDs).

Description

Retrieve recipient dynamic field definitions.

HTTP Method

GET

URL

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

...

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. 

...