On this page:
Table of Contents |
---|
Note |
---|
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
...
On this page:
Table of Contents |
---|
Note |
---|
It is recommended that you do not create a new list for each campaign, to avoid performance issues we suggest you not exceed the limit of 100 lists for each console account. |
...
Lists
Get List country codes
Anchor | ||||
---|---|---|---|---|
|
Description | Return the list of available country codes to create or update a list | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL | http://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/Countries | |||||||
Reference | Go to automated doc | |||||||
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) |
Get Time Zone codes
Anchor | ||||
---|---|---|---|---|
|
Description | Return the list of Time Zone codes to create or update a list |
---|---|
HTTP Method | GET |
URL | http://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/ |
TimeZones | ||||||||
Reference | Go to automated doc | |||||||
---|---|---|---|---|---|---|---|---|
JSON request (example) | none | |||||||
JSON response (example) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
...
language | html/xml |
---|
|
|
|
|
|
|
|
|
|
|
|
|
Create List
Note |
---|
Now the procedure to create a new list is easier and coherent with the information you provide creating it using your MailUp platform. Happy list creation! |
What are mandatory fields?
Mandatory fields are the required information you need to provide to create a new list. These information are the same you need to provide when you create a new list using your MailUp platform.
Here's the list of mandatory fields:
Field name | Type | Description |
---|---|---|
Name | String | List name (max 50 characters) |
Business | Boolean | True if your mailing is directed to businesses |
Customer | Boolean | True if your mailing is directed to consumers |
OwnerEmail | String | "FROM" email: the email address that is sending the message. Make sure that it is a recognizable address (e.g. it uses your Web site domain). |
ReplyTo | String | If your newsletter asks for a reply from the recipients, you may want the replies to be sent to a different address from the "FROM" email. Enter the reply-to address here: it must be a valid email address. If you leave the field blank, the "FROM" address (see "owneremail" field) will be used. |
DisplayAs | String | This is the name that will be displayed in the "To" section of the e-mail message heading. Name can be customized with dynamic fields using "campoN" labels (e.g. campo1,campo2, etc.), where N is the progressive number of the dynamic field |
NLSenderName | String | Email sender name: the person or entity that is sending the message. It could simply be your company name. |
CompanyName | String | The name of the company that is responsible for the messages sent out form this list. This field and the others that follows should be included as "sender information" in each message sent. Please refer to this page for more details |
ContactName | String | The contact reference name |
Address | String | The company's address |
City | String | The company's city |
CountryCode | String | The company's country. Please use one of the Country codes provided by the method Get List of Country codes. |
PermissionReminder | String | Use this field to remind recipients of why they are receiving messages. For example, you can use a message like this:You are receiving this message because you registered on our Web site and agreed to receive email communication from us. |
WebSiteUrl | String | The company's web site url |
Now that you know what we need to create your new list, let's create it!
Quick list creation
- Inherit missing values from a specified list (i.e., list identifier equals to 14)
| ||
Paging and filtering (example) |
---|
Create List
Anchor | ||||
---|---|---|---|---|
|
Tip |
---|
NEW: we've added a new method for creating lists and deprecated the previous one. We recommend all of you using the old method to switch to the new one, which supports the new mandatory sender fields and returns a more complete data set. |
Quick list creation
This is the minimum set of fields that are required to create a MailUp list using REST API. Please note that
- you always have to specify the so called "mandatory sender details" (see below)
- at least one between "IdSetting" and "UseDefaultSettings" has to be included in the request data
- you can also add any of the other optional fields (see the full list below)
Expand | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
Mandatory sender details are a list of values that have to be specified during the onboarding process or when creating a new MailUp list
|
Description | Create a new list | ||||||||
---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST | ||||||||
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List | ||||||||
Reference | |||||||||
JSON request (example) |
| ||||||||
JSON response (example) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- Inherit missing values from default settings. they are the values used to create the first list (with identifier equals to 1)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
language | js |
---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Advanced list creation
As you have seen in the response of the previous section, a list has many parameters that during creation you can inherit from a specified list or default settings. But sometimes you could have to create a list configuring not mandatory (like a description) or technical (like the maximum newsletter size) parameters. To get more in-depth, the following table shows the optional fields:
Field name | Type | Description |
---|---|---|
Description | String | Additional details about what the list is used for. |
Phone | String | The company's phone number |
PostalCode | String | The company's postal code |
StateOrProvince | String | The company's state or province |
TimeZoneCode | String | The list's time zone. Please use one of the TimeZoneCode codes provided by the method Get List of Time Zone codes. |
SmsSenderName | String | Default sender name for text messages. It can be a phone number (e.g. +393351234567) or a string (up to 11 chars, only letters and number). Please note that in some country, like Italy, some restrictions on SMS senders apply. Use MailUp admin console to verify if the specified sender is subject to limitations in some countries. |
DefaultPrefix | String | Default international prefix for mobile numbers (e.g. "0039" for Italy and "001" for United States) |
SendConfirmSms | Boolean | True when welcome SMS has to be sent for any new subscriber on SMS channel |
Charset | String | Text charset (see a list of Supported Charsets) |
Format | String | Format of emails to be sent with this list ("html" or "text") |
MultipartText | Boolean | Flag to automatically generate a text version of the message at sending stage |
KBMax | Integer | Message size beyond which a warning is generated. Suggested value = 100 |
NotifyEmail | String | Email address for unsubscribe notifications. Each time a recipient unsubscribes, an email will be sent to this address. |
OptoutType | Integer | Optout settings that apply when a recipient unsubscribe (0: One-click unsubscribe, 1: , 2: 3: Confirmed unsubscribe with options, 4: Confirmed unsubscribe with Preference Center) |
MultiOptoutList | String | Detail of the list IDs which will be viewed by the user in case of multiple optout (e.g. 1,2,3 etc.). Applies only when optout_type=2 |
SendEmailOptout | Boolean | When true a "goodbye email" is sent to recipient that unsubscribe |
SubscribedEmail | Boolean | True when welcome email has to be sent for any new subscriber (it works only when double optin is implemented) |
BouncedEmail | String | Address for error messages |
FrontendForm | Boolean | Enable hosted subscription forms, which you can view and edit under Settings > List settings > List Building Tools. |
Public | Boolean | Flag indicating if the list is visible in the public web library (if you set public=true the created list will be available in http://consoleUrl/frontend/nl_catalog.aspx) |
ScopeCode | Integer | select here which type of messages you are sending from this list:
|
TrackOnOpened | Boolean | True when link tracking has to be enabled at list level |
ConversionlabTrackCode | String | Code for tracking via conversionlab |
LinkTrackingParameters | String | It allows the integration between the list and third-party services (CRM, analytics). |
Disclaimer | String | Heading added to the messages in the list |
HeaderListUnsubscriber | String | Heading "LIST-UNSUBSCRIBE" added to the messages in the list. Suggested value = "<[listunsubscribe]>,<[mailto_uns]>" |
HeaderXAbuse | String | Heading "X-ABUSE" added to the messages in the list. Suggested value = "Please report abuse here: http://[host]/p" |
Now you know all fields that could be used to create a list, but before creating your first advance list please remember that:
Info | ||
---|---|---|
| ||
|
- Inherit missing values from a specified list (i.e., list identifier equals to 14)
| ||
Paging and filtering (example) |
---|
Advanced list creation
As you may have seen in the response object shown above, a MailUp list has many parameters that, during creation, you can inherit from a specified list or from the default settings. Sometimes you may have to customize your brand new list by overriding some of the default values (e.g. the description, the maximum newsletter size...).
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Description | Create a new list | ||||||||
---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST | ||||||||
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List | ||||||||
Reference | |||||||||
JSON request (example) |
|
|
|
|
|
|
|
|
|
|
|
|
- Inherit missing values from default settings. they are the values used to create the first list (with identifier equals to 1)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
language | js |
---|
| ||||||||
JSON response (example) |
|
---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Old api method
...
title | DEPRECATED - Old method to create a new list |
---|
Note |
---|
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. |
...
...
title | Click here to learn more about request parameters |
---|
...
| ||
Paging and filtering (example) |
---|
Old "create list" method
Anchor | ||||
---|---|---|---|---|
|
Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
copyTemplate Boolean | Deprecated field. Always use "false" value | copyWebhooks Boolean | When true and an existing list is set as template, then webhooks configuration is copied from that list | idSettings Integer | ID of an existing list to be used as template. This field is ignored when 'useDefaultSettings=true' | scope String | select here which type of messages you are sending from this list: "newsletters" (default), | "Direct_Advertising" (promotions, direct marketing messages), or "Transactional" (transactional messages like alerts, reminders, notifications) useDefaultSettings Boolean | When false, an existing list, specified by 'idSettings' field, is used as template. Otherwise default settings are used | CompanyName | String | The name of the company that is responsible for the messages sent out form this list. | This field and the others that follows should be included as "sender information" in each message sent. Please refer to this page for more details ContactName | String | The contact reference name | Address | String | The company's address | City | String | The company's city | PostalCode | String | The company's postal code | StateOrProvince | String | The company's state or province | CountryCode | String | The company's country. Please use one of the Country codes provided by the method Get List of Country codes. | Phone | String | The company's phone number | WebSiteUrl | String | The company's web site url | PermissionReminder | String | Use this field to remind recipients of why they are receiving messages. For example, you can use a message like this: | You are receiving this message because you registered on our Web site and agreed to receive email communication from us. JSON request (example) | Expand | Code Block |
|
Get list details
Anchor | ||||
---|---|---|---|---|
|
Description | UGet list details by id | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List} | |||||||
Reference | ||||||||
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) |
Update List
To update a list you have to provide an object that contains all the mandatory fields, even if you don't change them, and the optional fields that you want to modify.
We suggest you to take the result of the method to create a list (or the method to Get the list details), change what you need, and then provide the object to the PUT method.
Info | ||
---|---|---|
| ||
Updating a list, you can omit these fields:
Don't worry if you provide these values: the platform will ignore these values. |
Description | Update an existing list | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | PUT | |||||||
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List} | |||||||
Reference | For details about parameters you can look at Create List method. | |||||||
JSON request (example) |
| |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) |
Old update list method
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
JSON response (example) | List ID (e.g. 18)
| |
...
Delete List
Description |
---|
Delete an existing list |
HTTP Method |
---|
DELETE | |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/ |
---|
List/{id_List |
} | |
Reference | Go to automated doc |
---|
For details about parameters you can look at "Create List" method.
In addition, the Update method also requires the IdList field, which is the only mandatory field.
JSON request (example) | To ensure your intention to delete the list, we need to know 2 list-related values:
| |||||
---|---|---|---|---|---|---|
JSON response (example) |
|
language | html/xml |
---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Read Lists
| |||
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/List | |||||||
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 the list(s) whose name exactly matches the string 'Newsletter' using filterby="Name=='Newsletter'" then sort them by ID with orderby="idList desc". Parameter names can be retreived from the response body. Please note that filter matching is case sensitive.
Please note that also filtering with "Contains" is allowed but == is much more performing. |
Old read lists method
Expand | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||
|
...
Add recipients to a list - subscribe
You can use REST API to
- add and subscribe to 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
...
You should trust these email addresses for security reasons, so you can use TrustedSenders resource to do this job.
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
because the sender email address hasn't been verified yet. When the sender I want to trust click the verification link, the platform trusts the sender and the StatusDescription (and the StatusCode) changes due to some platform checks. Please consider trusted a sender with StatusCode different from 0. You can use this method to re-request to trust a sender email address: in fact, every time you call this method, even if the address is verified, you'll receive an email containing the verification link and the platform 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) |
| |||||||||||
JSON response (example) |
|
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) |
The table below shows that you have to consider in your integration.
The table above does not display statuses that means Ok, your sender's email address is trusted! |
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) |
The table below shows that you have to consider in your integration.
The table above does not display statuses that means Ok, your sender's email address is trusted! |
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. When you disable a sender, the trusted sender status is:
If you need to re-trust an email address, please do not disable it, but call the method to Trust an email address to send the email containing the verification link again. | ||||||
---|---|---|---|---|---|---|---|
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) |
| |||||
JSON response (example) |
| |||||
Paging and filtering (example) | none |
...
Update group
Description | Updatea 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) |
| |||||
JSON response (example) |
| |||||
Paging and filtering (example) | none |
Read Groups
Description | Readgroups 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 |
exactly matches the string 'Test' usingfilterby="Name.Contains('Test')" |
then sort them by ID orderby="idGroup asc". Parameter names can be retreived from the response body. Please note that |
filter matching is case sensitive.
|
|
|
...
Please note that also filtering with "Contains" is allowed but == is much more performing. |
Delete Group
Description | Deletea 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
...
- 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
...
- to "Update group membership" for details.
Remove recipients from a group (bulk removal from a group)
Description | Bulk removal of all recipients from a group | ||
---|---|---|---|
HTTP Method | DELETE | ||
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Group/{ID_GROUP}/Recipients | ||
Reference | Go to automated doc | ||
JSON request (example) |
| ||
JSON response (example) |
| ||
Paging and filtering (example) | none |
Tip | ||
---|---|---|
| ||
Click here to learn more about the difference between lists and groups in MailUp. |
...