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
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)
Click here to learn what are the "Mandatory sender details"
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
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.
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...).
Request parameters - the full list
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
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:
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"
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.
Default international prefix for mobile numbers (e.g. "0039" for Italy and "001" for United States)
description
String
Additional details about what the list is used for.
disclaimer
String
Heading added to the messages in the list
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
format
String
Format of emails to be sent with this list ("html" or "text")
frontendform
Boolean
Enable hosted subscription forms, which you can view and edit under Settings > List settings > List Building Tools.
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"
kbmax
Integer
Message size beyond which a warning is generated. Suggested value = 100
multi_optout_list
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
multipart_text
Boolean
Flag to automatically generate a text version of the message at sending stage
nl_sendername
String
Email sender name: the person or entity that is sending the message. It could simply be your company name.
notifyemail
String
Email address for unsubscribe notifications. Each time a recipient unsubscribes, an email will be sent to this address.
optout_type
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)
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.
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)
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.
sendconfirmsms
Boolean
True when welcome SMS has to be sent for any new subscriber on SMS channel
sendemailoptout
Boolean
When true a "goodbye email" is sent to recipient that unsubscribe
senderfax
String
Deprecated field, do not use it
senderfaxname
String
Deprecated field, do not use it
sms_sendername
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.
subscribedemail
Boolean
True when welcome email has to be sent for any new subscriber (it works only when double optin is implemented)
tracking
Boolean
True when link tracking has to be enabled at list level
Customer
Boolean
True if your mailing is directed to consumers
Name
String
List name (max 50 characters)
business
Boolean
True if your mailing is directed to businesses
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.
{
"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.
For details about parameters you can look at Create List deprecated method. In addition, the Update method also requires the IdList field, which is the only mandatory field.
JSON request (example)
{
"Name":"New Arrivals",
"description":"Use this list to inform subscribers about new products",
"IdList":2
}
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)
Retreive the list(s) whose name exactly matches the string 'Newsletter' usingfilterby="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
DEPRECATED - Old read lists method
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)
{"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.
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.
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.
The table below shows that you have to consider in your integration.
StatusCode
StatusDescription
Meaning
0
Not confirmed
You have just requested to trust an email address
1
Confirmed
Sender email address validated
2
Blocked
You disable a trusted sender
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. It could be useful if you need the status of a trusted sender email address without retrieve all data and navigate the list.
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.
{"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 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.
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 (bulk removal from a group)