| Table of Contents |
|---|
Accounts
...
How to create a console account
Refer to related document
Lists and groups
Click here to learn more about the difference between lists and groups in MailUp
How to get available lists
Note: methods for creating new lists through REST API are not yet available
| Description | Return the lists that are visible for authenticated user | |||||
|---|---|---|---|---|---|---|
| HTTP Method | GET | |||||
| URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/User/Lists | |||||
| JSON request (example) | none | |||||
| JSON response (example) |
| |||||
| Paging and filtering (example) | 5 items per page, get first page (count starts from zero)
Retreive all the lists whose name contains 'Newsletter' filterby="Name.Contains('Newsletter')" and sort them by ID orderby="idList desc". Parameter names can be retreived from the response body. Please note that "Contains" is case sensitive.
|
How to manage groups
Create
...
Description
...
Create a group into the specified list. Group ID is returned
...
HTTP Method
...
POST
...
URL
...
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Group
...
JSON request (example)
...
| Code Block | ||
|---|---|---|
| ||
{ "Deletable":true, "Name":"Test REST API Group", "Notes":"Notes should go here", "idList":2 } |
...
JSON response (example)
...
| Code Block | ||
|---|---|---|
| ||
{"Deletable":true,"Name":"Test REST API Group","Notes":"Notes should go here","idGroup":30,"idList":2} |
...
Paging and filtering (example)
none
Update
Description | Update a group starting from group ID | |||||
|---|---|---|---|---|---|---|
HTTP Method | PUT | |||||
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Group/{ID_GROUP} | |||||
JSON request (example) |
| |||||
JSON response (example) |
| |||||
Paging and filtering (example) | none
|
Read
...
Description
...
Read groups of specified list
...
HTTP Method
...
GET
...
URL
...
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Groups
...
JSON request (example)
...
none
...
JSON response (example)
...
| Code Block | ||
|---|---|---|
| ||
{"IsPaginated":false,"Items":[{"Deletable":true,"Name":"Test REST API Group","Notes":"I changed the notes again","idGroup":30,"idList":2},{"Deletable":true,"Name":"buddies","Notes":"","idGroup":27,"idList":2},{"Deletable":false,"Name":"Autoprofile","Notes":"Subscribers that changed their profile","idGroup":26,"idList":2},{"Deletable":false,"Name":"Subscribed from social network","Notes":"Subscribed with their social network account.","idGroup":25,"idList":2},{"Deletable":false,"Name":"TEST","Notes":"Used for test sending.","idGroup":24,"idList":2}],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":5} |
...
Paging and filtering (example)
5 items per page, get first page (count starts from zero)
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/2/Groups?PageNumber=0&PageSize=5
Retreive all the groups whose name contains 'Test' filterby="Name.Contains('Test')" and sort them by ID orderby="idGroup 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/2/Groups?filterby="Name.Contains(%27Test%27)"&orderby="idGroup+asc"
Delete
...
Description
...
Delete a group starting from group ID
...
HTTP Method
...
DELETE
...
URL
...
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Group/{ID_GROUP}
...
JSON request (example)
...
none
...
JSON response (example)
...
none
...
Paging and filtering (example)
none
Subscribers
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)
...
| Code Block | ||
|---|---|---|
| ||
{"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"
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)
| Code Block | ||
|---|---|---|
| ||
[{
"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)
...
| Code Block | ||
|---|---|---|
| ||
{"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)
...
| Code Block |
|---|
[{
"Email":"test25@example.com",
"Fields":[{
"Description":"Region",
"Id":8,
"Value":"Italy"
}],
"Name":"Test"
}] |
...
JSON response (example)
...
| Code Block | ||
|---|---|---|
| ||
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)
...
| Code Block | ||
|---|---|---|
| ||
{"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
when the specified recipient does not belong to list subscribers (i.e. it may be not existing but also unsubscribed or subscribed only to other MailUp lists for that console account) an empty list is returned
| |||||||
Paging and filtering (example) | 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
| Code Block |
|---|
[{
"Email":"test25@example.com",
"Fields":[{
"Description":"Region",
"Id":8,
"Value":"England"
}],
"Name":"Test"
"idRecipient":23
}] |
...
JSON response (example)
...
| 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
Email messages
coming soon
Statistics
coming soon
...