This page provides you information about how to use MailUp REST API to create email messages and to send them to specified recipients.
On this page:
Table of Contents |
---|
Email messages
An email message is always created inside the environment of a MailUp list, so it cannot be managed outside of that list.
Create a message
Description |
| ||
---|---|---|---|
HTTP Method | POST | ||
URL |
| ||
JSON request (example) |
| ||
JSON response (example) |
| ||
Paging and filtering (example) |
|
List Messages
Description | |||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
URL | Retreive all email messages of that list
Retreive only email messages that have been published (i.e. with public visibility, see details)
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | 2 items per page, get first page (count starts from zero)
Retreive messages that contain the word "test" in the subject field and order by ID. Note: search by text is case sensitive
|
Read message details
...
HTTP Method
...
GET
...
URL
...
Retrieve the email details by specified id
Code Block |
---|
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message} |
Get attachment list for the specified message id
Code Block |
---|
https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Attachment |
...
JSON request (example)
...
none
...
JSON response (example)
...
This page provides you information about how to use MailUp REST API to create email messages and to send them to specified recipients.
On this page:
Table of Contents |
---|
...
Email messages
An email message is always created inside the environment of a MailUp list, so it cannot be managed outside of that list.
Create a message
Description |
| ||
---|---|---|---|
HTTP Method | POST | ||
URL |
| ||
JSON request (example) |
| ||
JSON response (example) |
| ||
Paging and filtering (example) |
|
List Messages
Description | |||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
URL | Retreive all email messages of that list
Retreive only email messages that have been published (i.e. with public visibility, see details)
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | 2 items per page, get first page (count starts from zero)
Retreive messages that contain the word "test" in the subject field and order by ID. Note: search by text is case sensitive
|
Read message details
Description | ||||||
---|---|---|---|---|---|---|
HTTP Method | GET | |||||
URL | Retrieve the email details by specified id
Get attachment list for the specified message id
| |||||
JSON request (example) | none | |||||
JSON response (example) | ||||||
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) |
| Paging and filtering (example) |
Update message
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 status 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 |
| |||||||
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
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.
|
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.
Read group members
Description | Retreive only email subscribers that belong to specified group. Group members that are not subscribed on email channel are not returned | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL |
| |||||||
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
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.
|
Asynchronous import of recipients
Asynchronous import is used either for adding a single recipient to MailUp or to perform a bulk import.
Since it's not synchronous, it is fast but not immediate, please check the import status in order to know when the import task is completed.
Note |
---|
In case of bulk import, the upper limit for parameter size is configured as 500MB for each call. In any case we recommend to set a configurable upload size limit in your application and make a test with this size. When parameter 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
| |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | POST | |||||||
URL | Import recipients into a list
Import recipients into a group (a group always belongs to a single list)
| |||||||
JSON request (example) |
| |||||||
JSON response (example) | 3
| |||||||
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 |
| |||||
JSON request (example) | none
| |||||
JSON response (example) |
| |||||
Paging and filtering (example) | none
|
Manage a single email recipient / subscriber
Info |
---|
Definitions:
|
Create a recipient / subscriber
A single recipient can be added to a console account by calling Import Recipients and passing its details (at least one between email and mobile number and, optionally, personal data fields) as parameter.
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
Expand | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||
|
Update personal data fields of a subscriber
This section refers to changes on personal data fields of specified recipient (that must already exist)
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 |
| ||||
JSON request (example) |
| ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none
|
Update subscription status of a recipient
You can use API to force subscription or unsubscription status of an existing recipient on a specified list. Unsubscription though REST API can be performed only in this way, since bulk unsubscription is not available yet.
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
Unsubscribe
| ||||
JSON request (example) | none | ||||
JSON response (example) | none | ||||
Paging and filtering (example) | none
|
Update group membership of a subscriber
You can use API to add or remove an existing recipient from a specified group.
Update operation requires
- Recipient ID, refer to section "Check if a subscriber exists"
- The Group ID
Description | Add/remove the recipient with the related id to the specified group | ||||
---|---|---|---|---|---|
HTTP Method | POST/DELETE | ||||
URL | Add
Remove
| ||||
JSON request (example) | none | ||||
JSON response (example) | none | ||||
Paging and filtering (example) | none |
Check if a subscriber exists
With this method you can also retreive recipientID and personal data fields of the recipient with the specified email
Note | ||
---|---|---|
| ||
If you are using this method to retrieve recipient ID, unfotunately there is not a method that allows you to search recipient "by email address regardless the subscription status". Hence, it is possible that you have to make up to three search: in subscribed, in unsubscribed and finally in pending recipients of that list, |
| |||||||||
Paging and filtering (example) | 2 items per page, get first page (count starts from zero)
Retreive messages that contain the word "test" in the subject field and order by ID. Note: search by text is case sensitive
|
---|
Update message
Description | |
---|---|
HTTP Method | GET |
URL |
|
JSON request (example) | none |
JSON response (example) |
|
Paging and filtering (example) |
|
Manage tags
Description | |
---|---|
HTTP Method | GET |
URL |
|
JSON request (example) | none |
JSON response (example) |
|
Paging and filtering (example) |
Manage email attachments
Description | |
---|---|
HTTP Method | GET |
URL |
|
JSON request (example) | none |
JSON response (example) |
|
Paging and filtering (example) |
...
Send Email Messages
Send to all subscribers
Description | |
---|---|
HTTP Method | POST |
URL |
|
JSON request (example) | none |
JSON response (example) |
|
Paging and filtering (example) |
Send to a group
Description | |
---|---|
HTTP Method | POST |
URL |
|
JSON request (example) | none |
JSON response (example) |
|
Paging and filtering (example) |
Send to a recipient
Description | |
---|---|
HTTP Method | POST |
URL |
|
JSON request (example) | none |
JSON response (example) |
|
Paging and filtering (example) |
Retreive sending history
An email message can be sent several times. This feature allows to retreive details about each sending.
Description | |||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
URL | /Console/List/{id_List}/Email/{id_Message}/SendHistory | ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
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)"N/A |