New to MailUp?
Click here to learn more about the difference between lists and groups in MailUp.
On this page:
It is recommended that you do not create a new list for each campaign, to avoid performance issues we suggest you to not exceed the limit of 100 lists for each console account.
Lists
Note: methods for deleting MailUp lists through REST API are not yet available
Create List
MailUp copies data from the mandatory information fields of the list you are specifying as a reference, list 1 is used when 'useDefaultSettings=true'. This method fails returning a HTTP 500 error when the mandatory information fields to be copied are empty.
Description | Create a new list |
---|---|
HTTP Method | POST |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/User/Lists |
Reference | |
JSON request (example) | |
JSON response (example) | List ID (e.g. 18)
|
Paging and filtering (example) |
|
Update List
Description | Update an existing list |
---|---|
HTTP Method | PUT |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/User/List/{List_ID} |
Reference | For details about parameters you can look at "Create List" method. |
JSON request (example) | { "Name":"New Arrivals", "description":"Use this list to inform subscribers about new products", "IdList":2 } |
JSON response (example) | |
Paging and filtering (example) |
|
Read Lists
Description | Return the lists that are visible for authenticated user. If an existing list is not returned it is likely that the MailUp specified with the API is not enabled to see that list. Users with administrators grants can change this setting using the admin console account (i.e. the web application) |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/User/Lists |
Reference | Go to automated doc |
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.
|
Add recipients to a list - subscribe
You can use REST API to
- add and subscribe one or more recipients. See "Import recipients".
- force subscription of an existing recipient (i.e. unsubscribed or pending) by specifiying its ID. Refer to "Update subscription"
Remove recipients from a list - unsubscribe
REST API include either a method for single (refer to "Update subscription") or bulk (asynchronous import with "asOptout" option) unsubscription.
Trust your list's email addresses
When you create a list, you need to set two email addresses
- owneremail
- replyto
You should trust these email addresses for security reasons, so you can use TrustedSenders resource to do this job.
The following table shows the trusted sender statuses:
StatusCode | StatusDescription | Description |
---|---|---|
0 | NotConfirmed | You have just requested to trust an email address |
1 | Confirmed | You click on the verification link received by email: now youe email address is trusted |
2 | Blocked | You disable a trusted sender |
Trust an email address
Description | Use this method to trust a sender email address. Calling thie method, you'll send an email to the specified address containing a link to verify it. The response contains the value "StatusDescription": "NotConfirmed" because the sender email address hasn't been verified yet. Please note that every time you call this method specifying a sender email address, even if you have already verified it, you'll receive an email containing the verification link and the system updates the sender email address status to NotConfirmed. |
---|---|
HTTP Method | POST |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/TrustedSenders |
Reference | |
JSON request (example) | { "Email":"youremailaddress@yourdomain.eu" } |
JSON response (example) | { "AuthorizationDate": "", "CreationDate": "2016-11-28 12:34:36Z", "EmailAddress": "youremailaddress@yourdomain.eu", "IdTrustedSender": "ror11zuGscWcjl7m", "StatusCode": 0, "StatusDescription": "NotConfirmed", "UpdateDate": "2016-11-28 12:34:36Z" } |
Get trusted email addresses
Description | Use this method to retrieve the list of trusted senders' email addresses. |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/TrustedSenders |
Reference | |
JSON request (example) | None |
JSON response (example)
| { "IsPaginated": false, "Items": [ { "AuthorizationDate": "2016-09-22 16:43:55Z", "CreationDate": "2016-09-22 16:43:45Z", "EmailAddress": "youremailaddress@yourdomain.eu", "IdTrustedSender": "ror11zuGscWcjl7m", "StatusCode": 7, "StatusDescription": "NotConfirmed", "UpdateDate": "2016-09-22 16:43:55Z" } ], "PageNumber": 0, "PageSize": 20, "Skipped": 0, "TotalElementsCount": 4 } |
Get a trusted email address details
Description | Use this method to retrieve a trusted sender's email address details. |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/TrustedSenders/{IdTrustedSender} |
Reference | |
JSON request (example) | None |
JSON response (example)
| { "AuthorizationDate": "2016-09-22 16:43:55Z", "CreationDate": "2016-09-22 16:43:45Z", "EmailAddress": "youremailaddress@yourdomain.eu", "IdTrustedSender": "ror11zuGscWcjl7m", "StatusCode": 7, "StatusDescription": "NotConfirmed", "UpdateDate": "2016-09-22 16:43:55Z" } |
Disable an email address
Description | Use this method to disable a trusted sender. When you disable an email address, you cannot trust it again in the future. | ||||||
---|---|---|---|---|---|---|---|
HTTP Method | DELETE | ||||||
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/TrustedSenders/{IdTrustedSender} | ||||||
Reference | |||||||
JSON request (example) | For security reason, you need to submit the email address to disable using the If-match header.
| ||||||
JSON response (example) |
| ||||||
Groups
Create Group
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 |
Reference | Go to automated doc |
JSON request (example) | { "Name":"Test REST API Group", "Notes":"Notes should go here" } |
JSON response (example) | {"Deletable":true,"Name":"Test REST API Group","Notes":"Notes should go here","idGroup":30,"idList":2} |
Paging and filtering (example) | none |
Update group
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} |
Reference | Go to automated doc |
JSON request (example) | { "Name":"Test REST API Group renamed", "Notes":"I changed the notes again"} |
JSON response (example) | {"Deletable":true,"Name":"Test REST API Group renamed","Notes":"I changed the notes again","idGroup":30,"idList":2} |
Paging and filtering (example) | none |
Read Groups
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 |
Reference | Go to automated doc |
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 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.
|
Delete Group
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} |
Reference | Go to automated doc |
JSON request (example) | none |
JSON response (example) | none |
Paging and filtering (example) | none |
Add recipients to a group
You can use REST API to
- add one or more recipients to a group and subscribe them to the MailUp list that contains the group. This double action is performed by a single operation, see "Import recipients" for details.
- add to a group an existing recipient by specifiying its ID. This operation also forces the subscription to the MailUp list of that group, refer to "Update group membership" for details.
Remove recipients from a group
REST API does not include yet a method for a bulk removal from a group, while the removal of a single recipient by specifying its ID is available. Refer to "Update group membership"