Manage Lists and Groups

Manage Lists and Groups

On this page:

 

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

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)

[ { "CountryCode": "AF", "CountryName": "Afghanistan" }, { "CountryCode": "AL", "CountryName": "Albania" }, { "CountryCode": "DZ", "CountryName": "Algeria" }, { "CountryCode": "AR", "CountryName": "Argentina" }, ... { "CountryCode": "VN", "CountryName": "Vietnam" }, { "CountryCode": "YE", "CountryName": "Yemen" }, { "CountryCode": "ZW", "CountryName": "Zimbabwe" } ]

Paging and filtering (example)

 

Get Time Zone codes

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)

[ { "OffsetFromUTC": "0:00:00", "TimeZoneCode": "UTC+00:00.0", "TimeZoneDescription": "(UTC) Casablanca", "TimeZoneName": "Morocco Standard Time" }, { "OffsetFromUTC": "0:00:00", "TimeZoneCode": "UTC+00:00.1", "TimeZoneDescription": "(UTC) Coordinated Universal Time", "TimeZoneName": "UTC" }, { "OffsetFromUTC": "0:00:00", "TimeZoneCode": "UTC+00:00.2", "TimeZoneDescription": "(UTC) Dublin, Edinburgh, Lisbon, London", "TimeZoneName": "GMT Standard Time" }, { "OffsetFromUTC": "0:00:00", "TimeZoneCode": "UTC+00:00.3", "TimeZoneDescription": "(UTC) Monrovia, Reykjavik", "TimeZoneName": "Greenwich Standard Time" }, ... { "OffsetFromUTC": "-11:00:00", "TimeZoneCode": "UTC-11:00.0", "TimeZoneDescription": "(UTC-11:00) Coordinated Universal Time-11", "TimeZoneName": "UTC-11" }, { "OffsetFromUTC": "-12:00:00", "TimeZoneCode": "UTC-12:00.0", "TimeZoneDescription": "(UTC-12:00) International Date Line West", "TimeZoneName": "Dateline Standard Time" } ]

Paging and filtering (example)

 

Create List

 

Apr 12, 2017 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)

 

Mandatory sender details are a list of values that have to be specified during the onboarding process or when creating a new MailUp list
Here is the full list:

Field name

Type

Description

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).
For security reason, please trust this email address, as explain by the method Trust an email address.

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.
For security reason, please trust this email address, as explain by the method Trust an email address

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

Description

Create a new list

HTTP Method

POST

URL

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List

Reference

Go to automated doc

JSON request (example)

  • Inherit missing values from a specified list (i.e., list identifier equals to 14)

{ "Name":"New Arrivals", "Business":true, "Customer":true, "OwnerEmail":"jane@example.com", "ReplyTo":"mike@example.com", "NLSenderName": "Your sender name", "CompanyName":"Your company", "ContactName":"Your name", "Address":"Your address", "City":"Your city", "CountryCode":"IT", "PermissionReminder":"Your permission reminder", "WebSiteUrl":"Your site", "IdSettings":14 }
  • Inherit missing values from default settings. they are the values used to create the first list (with identifier equals to 1)

{ "Name":"New Arrivals", "Business":true, "Customer":true, "OwnerEmail":"jane@example.com", "ReplyTo":"mike@example.com", "NLSenderName": "Your sender name", "CompanyName":"Your company", "ContactName":"Your name", "Address":"Your address", "City":"Your city", "CountryCode":"IT", "PermissionReminder":"Your permission reminder", "WebSiteUrl":"Your site", "UseDefaultSettings":true }

JSON response (example)

{ "IdList": 19, "ListGuid": "57f9c675-63d6-498f-91b6-7f60f9f30b2e", "Name": "New Arrivals", "Description": "", "NLSenderName": "Your sender name", "OwnerEmail": "jane@example.com", "PermissionReminder": "Your permission reminder", "Address": "Your address", "Business": true, "City": "Your city", "CompanyName": "Your company", "ContactName": "Your name", "CountryCode": "IT", "Customer": true, "DisplayAs": "", "Phone": "", "PostalCode": "", "ReplyTo": "mike@example.com", "StateOrProvince": "", "WebSiteUrl": "www.mailup.it" "BouncedEmail": null, "Charset": "UTF-8", "ConversionlabTrackCode": "", "DefaultPrefix": "0039", "Disclaimer": "Per l'informativa sulla privacy D.Lgs 196/2003 visitare l'home page del sito. <br/> Policy AntiSPAM garantita da <a href=\"http://www.mailup.it/email-marketing/policy-antispam.asp\" target=_blank><img src=\"http://doc.mailupnet.it/logo_small_R.gif\" border=\"0\" align=\"middle\" /></a>", "Format": "html", "FrontendForm": true, "HeaderListUnsubscriber": "<[listunsubscribe]>,<[mailto_uns]>", "HeaderXAbuse": "Please report abuse here: http://www.mailup.it/email-marketing/Policy-antispam_ENG.asp", "KBMax": 100, "LinkTrackingParameters": "", "MultiOptoutList": "19", "MultipartText": true, "NotifyEmail": "", "OptoutType": 3, "Public": true, "ScopeCode": 0, "SendConfirmSms": false, "SendEmailOptout": false, "SmsSenderName": "", "SubscribedEmail": true, "TimeZoneCode": "UTC+01:00.0", "TrackOnOpened": true }

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...).

Field name

Type

Description

Field name

Type

Description

Description

String

Additional details about what the list is used for.

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

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: 

Confirmed unsubscribe

, 2: 

Confirmed unsubscribe with list preferences,

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:

  • 0: Newsletters (default),

  • 1: Direct_Advertising (promotions, direct marketing messages)

  • 2: Transactional (transactional messages like alerts, reminders, notifications)

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).
Please, do not use question marks in this field.
The platform appends this value to all tracking links sent via email.
For Google Analytics use URL builder.

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"

 

 

 

Description

Create a new list

HTTP Method

POST

URL

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List

Reference

Go to automated doc

JSON request (example)

  • Inherit missing values from a specified list (i.e., list identifier equals to 14)

{ "Name": "New Arrivals", "Business": true, "Customer": true, "OwnerEmail": "jane@example.com", "ReplyTo": "mike@example.com", "DisplayAs": "", "NLSenderName": "Your sender name", "CompanyName": "Your company", "ContactName": "Your name", "Address": "Your address", "City": "Your city", "CountryCode": "IT", "PermissionReminder": "Your permission reminder", "WebSiteUrl": "www.mailup.it", "Description": "", "Phone": "", "PostalCode": "", "StateOrProvince": "", "TimeZoneCode": "UTC+01:00.0", "SmsSenderName": "", "DefaultPrefix": "0039", "SendConfirmSms": false, "Charset": "UTF-8", "Format": "html", "MultipartText": true, "KBMax": 100, "NotifyEmail": "", "OptoutType": 3, "MultiOptoutList": "19", "SendEmailOptout": false, "SubscribedEmail": true, "BouncedEmail": null, "FrontendForm": true, "Public": true, "ScopeCode": 0, "TrackOnOpened": true "ConversionlabTrackCode": "", "LinkTrackingParameters": "", "Disclaimer": "Per l'informativa sulla privacy D.Lgs 196/2003 visitare l'home page del sito. <br/> Policy AntiSPAM garantita da <a href=\"http://www.mailup.it/email-marketing/policy-antispam.asp\" target=_blank><img src=\"http://doc.mailupnet.it/logo_small_R.gif\" border=\"0\" align=\"middle\" /></a>", "HeaderListUnsubscriber": "<[listunsubscribe]>,<[mailto_uns]>", "HeaderXAbuse": "Please report abuse here: http://www.mailup.it/email-marketing/Policy-antispam_ENG.asp", "IdSettings": 14 }
  • Inherit missing values from default settings. they are the values used to create the first list (with identifier equals to 1)

{ "Name": "New Arrivals", "Business": true, "Customer": true, "OwnerEmail": "jane@example.com", "ReplyTo": "mike@example.com", "DisplayAs": "", "NLSenderName": "Your sender name", "CompanyName": "Your company", "ContactName": "Your name", "Address": "Your address", "City": "Your city", "CountryCode": "IT", "PermissionReminder": "Your permission reminder", "WebSiteUrl": "www.mailup.it", "Description": "", "Phone": "", "PostalCode": "", "StateOrProvince": "", "TimeZoneCode": "UTC+01:00.0", "SmsSenderName": "", "DefaultPrefix": "0039", "SendConfirmSms": false, "Charset": "UTF-8", "Format": "html", "MultipartText": true, "KBMax": 100, "NotifyEmail": "", "OptoutType": 3, "MultiOptoutList": "19", "SendEmailOptout": false, "SubscribedEmail": true, "BouncedEmail": null, "FrontendForm": true, "Public": true, "ScopeCode": 0, "TrackOnOpened": true "ConversionlabTrackCode": "", "LinkTrackingParameters": "", "Disclaimer": "Per l'informativa sulla privacy D.Lgs 196/2003 visitare l'home page del sito. <br/> Policy AntiSPAM garantita da <a href=\"http://www.mailup.it/email-marketing/policy-antispam.asp\" target=_blank><img src=\"http://doc.mailupnet.it/logo_small_R.gif\" border=\"0\" align=\"middle\" /></a>", "HeaderListUnsubscriber": "<[listunsubscribe]>,<[mailto_uns]>", "HeaderXAbuse": "Please report abuse here: http://www.mailup.it/email-marketing/Policy-antispam_ENG.asp", "UseDefaultSettings": true }

JSON response (example)

{ "IdList": 19, "ListGuid": "57f9c675-63d6-498f-91b6-7f60f9f30b2e", "Name": "New Arrivals", "Description": "", "NLSenderName": "Your sender name", "OwnerEmail": "jane@example.com", "PermissionReminder": "Your permission reminder", "Address": "Your address", "Business": true, "City": "Your city", "CompanyName": "Your company", "ContactName": "Your name", "CountryCode": "IT", "Customer": true, "DisplayAs": "", "Phone": "", "PostalCode": "", "ReplyTo": "mike@example.com", "StateOrProvince": "", "WebSiteUrl": "www.mailup.it" "BouncedEmail": null, "Charset": "UTF-8", "ConversionlabTrackCode": "", "DefaultPrefix": "0039", "Disclaimer": "Per l'informativa sulla privacy D.Lgs 196/2003 visitare l'home page del sito. <br/> Policy AntiSPAM garantita da <a href=\"http://www.mailup.it/email-marketing/policy-antispam.asp\" target=_blank><img src=\"http://doc.mailupnet.it/logo_small_R.gif\" border=\"0\" align=\"middle\" /></a>", "Format": "html", "FrontendForm": true, "HeaderListUnsubscriber": "<[listunsubscribe]>,<[mailto_uns]>", "HeaderXAbuse": "Please report abuse here: http://www.mailup.it/email-marketing/Policy-antispam_ENG.asp", "KBMax": 100, "LinkTrackingParameters": "", "MultiOptoutList": "19", "MultipartText": true, "NotifyEmail": "", "OptoutType": 3, "Public": true, "ScopeCode": 0, "SendConfirmSms": false, "SendEmailOptout": false, "SmsSenderName": "", "SubscribedEmail": true, "TimeZoneCode": "UTC+01:00.0", "TrackOnOpened": true }

Paging and filtering (example)

 

Old "create list" method

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

Go to automated doc

Mandatory fields are marked in bold. To have an example of data formats you can have a look at the response of "Update List" method

JSON request (example)

{ "Name":"New Arrivals", "useDefaultSettings":false, "idSettings":1, "business":true, "Customer":true, "scope":"newsletters", "owneremail":"jane@example.com", "format":"html", "copyTemplate":true, "copyWebhooks":true, "charset":"UTF-8", "public":true, "tracking":true, "optout_type":0, "sendemailoptout":false, "frontendform":true, "headerxabuse":"Please report abuse here: http://[host]/p", "kbmax":100, "replyto":"mike@example.com", "headerlistunsubscriber":"<[listunsubscribe]>,<[mailto_uns]>", "multipart_text":true, "subscribedemail":true, "sendconfirmsms":false, "CompanyName":"Your company", "ContactName":"Your name", "Address":"Your address", "City":"Your city", "PostalCode":"26100", "StateOrProvince":"Cremona", "CountryCode":"IT", "PermissionReminder":"Your permission reminder", "WebSiteUrl":"Your site", "Phone":"Your phone number", }

JSON response (example)

List ID (e.g. 18)

 

Paging and filtering (example)

 

Get list details 

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

Go to automated doc 

JSON request (example)

none

JSON response (example)

{ "BouncedEmail": null, "Charset": "UTF-8", "ConversionlabTrackCode": "", "DefaultPrefix": "0039", "Description": "I ADDED THIS FEW LINES TO DESCRIBE THE PURPOUS OF THIS LIST", "Disclaimer": "Per l'informativa sulla privacy D.Lgs 196/2003 visitare l'home page del sito. <br/> Policy AntiSPAM garantita da <a href=\"http://www.mailup.it/email-marketing/policy-antispam.asp\" target=_blank><img src=\"http://doc.mailupnet.it/logo_small_R.gif\" border=\"0\" align=\"middle\" /></a>", "Format": "html", "FrontendForm": true, "HeaderListUnsubscriber": "<[listunsubscribe]>,<[mailto_uns]>", "HeaderXAbuse": "Please report abuse here: http://www.mailup.it/email-marketing/Policy-antispam_ENG.asp", "KBMax": 100, "LinkTrackingParameters": "", "MultiOptoutList": "21", "MultipartText": true, "NotifyEmail": null, "OptoutType": 3, "Public": true, "ScopeCode": 0, "SendConfirmSms": false, "SendEmailOptout": false, "SmsSenderName": "", "SubscribedEmail": true, "TimeZoneCode": "UTC+01:00.0", "TrackOnOpened": true, "Address": "Your address", "Business": true, "City": "Your city", "CompanyName": "Your MODIFIED company NAME", "ContactName": "Your name", "CountryCode": "IT", "Customer": true, "DisplayAs": "Your sender name", "IdList": 21, "ListGuid": "1239a201-47d1-46fa-b5a1-384ad6e78c60", "NLSenderName": "Your list name", "Name": "NEW LIST NAME", "OwnerEmail": "jane@example.com", "PermissionReminder": "Your permission reminder", "Phone": "", "PostalCode": "", "ReplyTo": "mike@example.com", "StateOrProvince": "", "WebSiteUrl": "My NEW site" }

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.

It's not necessary...

Updating a list, you can omit these fields:

  • IdSettings and UseDefaultSettings: they are necessary only to create a list

  • IdList and ListGuid: you cannot change these values, so do not provide them

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

Go to automated doc 

For details about parameters you can look at Create List method.

JSON request (example)

{ "Name": "NEW LIST NAME", "Description": "I ADDED THIS FEW LINES TO DESCRIBE THE PURPOUS OF THIS LIST", "CompanyName": "Your MODIFIED company NAME", "WebSiteUrl": "My NEW site", "BouncedEmail": null, "Charset": "UTF-8", "ConversionlabTrackCode": "", "DefaultPrefix": "0039", "Disclaimer": "Per l'informativa sulla privacy D.Lgs 196/2003 visitare l'home page del sito. <br/> Policy AntiSPAM garantita da <a href=\"http://www.mailup.it/email-marketing/policy-antispam.asp\" target=_blank><img src=\"http://doc.mailupnet.it/logo_small_R.gif\" border=\"0\" align=\"middle\" /></a>", "Format": "html", "FrontendForm": true, "HeaderListUnsubscriber": "<[listunsubscribe]>,<[mailto_uns]>", "HeaderXAbuse": "Please report abuse here: http://www.mailup.it/email-marketing/Policy-antispam_ENG.asp", "KBMax": 100, "LinkTrackingParameters": "", "MultiOptoutList": "21", "MultipartText": true, "NotifyEmail": null, "OptoutType": 3, "Public": true, "ScopeCode": 0, "SendConfirmSms": false, "SendEmailOptout": false, "SmsSenderName": "", "SubscribedEmail": true, "TimeZoneCode": "UTC+01:00.0", "TrackOnOpened": true, "Address": "Your address", "Business": true, "City": "Your city", "ContactName": "Your name", "CountryCode": "IT", "Customer": true, "DisplayAs": "Your sender name", "NLSenderName": "Your list name", "OwnerEmail": "jane@example.com", "PermissionReminder": "Your permission reminder", "Phone": "", "PostalCode": "", "ReplyTo": "mike@example.com", "StateOrProvince": "" }

JSON response (example)

{ "BouncedEmail": null, "Charset": "UTF-8", "ConversionlabTrackCode": "", "DefaultPrefix": "0039", "Description": "I ADDED THIS FEW LINES TO DESCRIBE THE PURPOUS OF THIS LIST", "Disclaimer": "Per l'informativa sulla privacy D.Lgs 196/2003 visitare l'home page del sito. <br/> Policy AntiSPAM garantita da <a href=\"http://www.mailup.it/email-marketing/policy-antispam.asp\" target=_blank><img src=\"http://doc.mailupnet.it/logo_small_R.gif\" border=\"0\" align=\"middle\" /></a>", "Format": "html", "FrontendForm": true, "HeaderListUnsubscriber": "<[listunsubscribe]>,<[mailto_uns]>", "HeaderXAbuse": "Please report abuse here: http://www.mailup.it/email-marketing/Policy-antispam_ENG.asp", "KBMax": 100, "LinkTrackingParameters": "", "MultiOptoutList": "21", "MultipartText": true, "NotifyEmail": null, "OptoutType": 3, "Public": true, "ScopeCode": 0, "SendConfirmSms": false, "SendEmailOptout": false, "SmsSenderName": "", "SubscribedEmail": true, "TimeZoneCode": "UTC+01:00.0", "TrackOnOpened": true, "Address": "Your address", "Business": true, "City": "Your city", "CompanyName": "Your MODIFIED company NAME", "ContactName": "Your name", "CountryCode": "IT", "Customer": true, "DisplayAs": "Your sender name", "IdList": 21, "ListGuid": "1239a201-47d1-46fa-b5a1-384ad6e78c60", "NLSenderName": "Your list name", "Name": "NEW LIST NAME", "OwnerEmail": "jane@example.com", "PermissionReminder": "Your permission reminder", "Phone": "", "PostalCode": "", "ReplyTo": "mike@example.com", "StateOrProvince": "", "WebSiteUrl": "My NEW site" }

Paging and filtering (example)

 

Old update list method