This page provides you information about how to manage recipients (subscribe, unsubscribe, update personal data).
Things to know about recipients:
Subscription and Unsubscription
- subscription and unsubscription always refer to a specific MailUp list and to a specified MailUp channel (email, SMS, Fax)
- Subscription and unsubscription does not apply to groups: a recipient may belong to zero, one or more groups of a list
- For each MailUp channel, the recipient's statuses "subscribed", "unsubscribed" and "pending" (when Confirmed Opt-In, COI, applies) are mutually exclusive on a specified list
- Email address and mobile number are primary keys in MailUp: there cannot be two recipients with the same email address or with the same mobile phone number
Personal data fields
- Personal data fields are shared through all the channels of a console account
Automatic unsubscription
- Recipients can be automatically unsubscribed from the email channel of all lists of a console account in case of hard bounces
- Recipients are automatically unsubscribed from the email channel a specified lists of a console account in case of feedback loop (i.e. reported as spam)
Importing recipients into MailUp
- You can use API to force opt-in for unsubscribed recipients, but you shall do that only when the recipient really wants to be subscribed again. In case of abuses your console account may be blocked.
- You cannot use API to force opt-in in case of unsubscription due to bounces
- You can use API to import recipients into a specified list/group. Synchronous import has to be used to manage a single subscription and, in some cases, it can be applied even to a very small set of recipients. With more than ten recipients asynchronous import is recommended
On this page:
You can subscribe a recipient to one or more lists or groups and you can also set personal data fields of the recipient.
Retrieve all subscribed/unsubscribed from a list
Subscribed
Description | Retreive subscribers of specified list |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Recipients/Subscribed |
JSON request (example) | none |
JSON response (example) | {"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)
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.
|
Unsubscribed
As for "subscribed", but in this case the endpoint is /Console/List/{ID_LIST}/Recipients/Unsubscribed
Asynchronous import of recipients
Asynchronous import is required when you have more than 10 recipients to be imported. It is fast but not immediate, please check the import status in order to know when the import task is completed.
When more import requests are pending, MailUp processes them in a sequential order.
Start import
Description | Create and execute a task that imports specified recipients. Import task ID is returned |
---|---|
HTTP Method | POST |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{ID_GROUP}/Recipients |
JSON request (example) | Import one recipient. Notes: it is an array you can import as many recipient as you want, up to 1MB of data (split into more import tasks if you have more recipients) [{ "Email":"john@doe.com", "Name":"john doe", "Fields":{ "FirstName":"john", "LastName":"doe", "Company":"john's Uber Awesome Company", "Phone":"1115559999", "LatestOrderId":1000, "LatestOrderDate":"2013-12-13T16:52:08.3112622Z", "LatestOrderAmount":100.99, "LatestOrderProductIds":[100,101], "LatestOrderCategoryIds":[1,2], "LatestShippedOrderId":1000, "LatestShippedOrderDate":"2013-12-14T16:52:08.3112622Z", "TotalOrdered":100.99, "TotalOrderedLastYear":825.99, "TotalOrderedLastMonth":100.99, "AllOrderedProductIds":[100,101]} }]
|
JSON response (example) | 3
|
Paging and filtering (example) | none |
Read Import status
Description | Read status of an import task by specifying its ID |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Import/{IMPORT_ID} |
JSON request (example) | none
|
JSON response (example) | {"Completed":true,"CreatedRecipients":1,"ImportedRecipients":0,"NotValidRecipients":0,"UpdatedRecipients":0,"ValidRecipients":1,"idImport":3} |
Paging and filtering (example) | none |
How to subscribe/unsubscribe a single email recipient (synchronous)
Create (subscribe)
Description | Add a new subscriber to the specified list |
---|---|
HTTP Method | POST |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Recipients |
JSON request (example) | [{ "Email":"test25@example.com", "Fields":[{ "Description":"Region", "Id":8, "Value":"Italy" }], "Name":"Test" }]
|
JSON response (example) | 8 |
Paging and filtering (example) | none |
How to update fields of a single email recipient
First of all, you need to get the ID of dynamic fields, then you can update the personal data fields of a subscriber. Please note that the subscriber must already exist.
Retrieve recipient dynamic field definitions
Description | Retrieve recipient dynamic field definitions. |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Recipient/DynamicFields |
JSON request (example) | none
|
JSON response (example) | {"IsPaginated":true,"Items":[{"Description":"AllOrderedProductIDs","Id":26},{"Description":"TotalOrderedLast30d","Id":25},{"Description":"TotalOrderedLast12m","Id":24},{"Description":"TotalOrdered","Id":23},{"Description":"LatestAbandonedCartID","Id":22},{"Description":"LatestAbandonedCartTotal","Id":21},{"Description":"LatestAbandonedCartDate","Id":20},{"Description":"LatestShippedOrderID","Id":19},{"Description":"LatestShippedOrderDate","Id":18},{"Description":"LatestOrderCategoryIDs","Id":17},{"Description":"LatestOrderProductIDs","Id":16},{"Description":"LatestOrderAmount","Id":15},{"Description":"LatestOrderDate","Id":14},{"Description":"LatestOrderID","Id":13},{"Description":"CustomerID","Id":12},{"Description":"phone","Id":11},{"Description":"Gender ","Id":10},{"Description":"Address","Id":9},{"Description":"Region","Id":8},{"Description":"State","Id":7}],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":26} |
Paging and filtering (example) | Use endpoint /Console/Recipient/DynamicFields?&orderby="Id+asc" to get a list that is ordered by Id |
Check if a subscriber exists
With this method you can also retreive recipientID and personal data fields of specified subscriber
Description | Check subscriber and retreive data |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/3/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 {"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 {"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)" |
Change a personal data field of an existing subscriber
Description | Retrieve recipient dynamic field definitions. |
---|---|
HTTP Method | PUT |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Recipient/DynamicFields |
JSON request (example) | Modifying the "Region" field [{ "Email":"test25@example.com", "Fields":[{ "Description":"Region", "Id":8, "Value":"England" }], "Name":"Test" "idRecipient":23 }]
|
JSON response (example) | {"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 |
Email messages
coming soon
Statistics
coming soon