Versions Compared

Old Version 1

changes.mady.by.user MailUp Dev Team

Saved on

compared with

New Version 2

changes.mady.by.user MailUp Dev Team

Saved on

Key

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

Table of Contents

Accounts

How to get account info
DescriptionReturns profile info for authenticated user account
HTTP MethodGET
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Authentication/Info
JSON request parameters (example)none
JSON response (example){"Company":"nweb srl","IsTrial":true,"UID":"388","Username":"m1234","Version":"8.5"}
Paging and filtering (example)none
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

DescriptionReturn the lists that are visible for authenticated user
HTTP MethodGET
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/User/Lists
JSON request (example)none
JSON response (example)
Code Block
languagehtml/xml
{"IsPaginated":false,"Items":[{"Company":"","Description":"","Name":"Second List ","idList":2,"listGuid":"f34e5054-5555-4444-ffff-51acc36ae104"},{"Company":"","Description":"This is a description","Name":"Newsletter ","idList":1,"listGuid":"49494949-4444-9999-8888-185543409eb7"}],"PageNumber":0,"PageSize":5,"Skipped":0,"TotalElementsCount":2}
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
languagehtml/xml
{ "Deletable":true, "Name":"Test REST API Group", "Notes":"Notes should go here", "idList":2 }

...

JSON response (example)

...

Code Block
languagehtml/xml
{"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)

Code Block
languagehtml/xml
{ "Deletable":true, "Name":"Test REST API Group", "Notes":"I changed the notes again", "idGroup":30, "idList":2 }

JSON response (example)

Code Block
languagehtml/xml
{"Deletable":true,"Name":"Test REST API Group","Notes":"I changed the notes again","idGroup":30,"idList":2}

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
languagehtml/xml
{"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)

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

 

 

...

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

Things to know about recipients:

  • subscription and unsubscription always refer to a specific MailUp list and to a specified MailUp channel (email, SMS, Fax)
  • personal data fields are shared through all the channels of a console account
  • for each MailUp channel, the recipient's statuses "subscribed", "unsubscribed" and "pending" (when Confirmed Opt-In, COI, applies) are mutually exclusive
  • There cannot be two recipients with the same email address or with the same mobile phone number
  • Recipients can be automatically unsubscribed in case of hard bounces
  • 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 can be applied even to a very small set of recipients. With more than ten recipients asynchronous import is recommended 


On this page:

Table of Contents

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


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
languagehtml/xml
[{
"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
languagehtml/xml
{"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
languagehtml/xml
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
languagehtml/xml
{"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

Code Block
languagehtml/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}

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