Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Get List country codes
Anchor
getlistcountrycodes
getlistcountrycodes

DescriptionReturn the list of available country codes to create or update a list
HTTP MethodGET
URLhttp://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/Countries
ReferenceGo to automated doc
JSON request (example)none
JSON response (example)


Expand


Code Block
languagehtml/xml
[
  {
    "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
Anchor
getlisttimezonecodes
getlisttimezonecodes

DescriptionReturn the list of Time Zone codes to create or update a list
HTTP MethodGET
URLhttp://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/TimeZones
ReferenceGo to automated doc
JSON request (example)none
JSON response (example)


Expand


Code Block
languagehtml/xml
[
  {
    "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
Anchor
createlist
createlist

...


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
titleClick 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 nameTypeDescription
NameStringList name (max 50 characters)
BusinessBooleanTrue if your mailing is directed to businesses
CustomerBooleanTrue if your mailing is directed to consumers
OwnerEmailString

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

ReplyToString

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

NLSenderNameString

Email sender name: the person or entity that is sending the message. It could simply be your company name.

CompanyNameStringThe 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
ContactNameStringThe contact reference name
AddressStringThe company's address
CityStringThe company's city
CountryCodeStringThe company's country. Please use one of the Country codes provided by the method Get List of Country codes.
PermissionReminderStringUse 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.
WebSiteUrlStringThe company's web site url



DescriptionCreate a new list
HTTP MethodPOST
URLhttps://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)
Expand


Code Block
{
   "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)
Expand


Code Block
{
   "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)


Expand


Code Block
languagejs
{
  "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...).

Expand
titleRequest parameters - the full list


Field nameTypeDescription
DescriptionStringAdditional details about what the list is used for.
DisplayAsStringThis 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
PhoneStringThe company's phone number
PostalCodeStringThe company's postal code
StateOrProvinceStringThe company's state or province
TimeZoneCodeString

The list's time zone. Please use one of the TimeZoneCode codes provided by the method Get List of Time Zone codes.

SmsSenderNameStringDefault 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.
DefaultPrefixStringDefault international prefix for mobile numbers (e.g. "0039" for Italy and "001" for United States)
SendConfirmSmsBooleanTrue when welcome SMS has to be sent for any new subscriber on SMS channel
CharsetStringText charset (see a list of Supported Charsets)
FormatStringFormat of emails to be sent with this list ("html" or "text")
MultipartTextBooleanFlag to automatically generate a text version of the message at sending stage
KBMaxIntegerMessage size beyond which a warning is generated. Suggested value = 100
NotifyEmailStringEmail address for unsubscribe notifications. Each time a recipient unsubscribes, an email will be sent to this address.
OptoutTypeIntegerOptout settings that apply when a recipient unsubscribe (0: One-click unsubscribe, 1: , 2: 3: Confirmed unsubscribe with options, 4: Confirmed unsubscribe with Preference Center)
MultiOptoutListStringDetail 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
SendEmailOptoutBooleanWhen true a "goodbye email" is sent to recipient that unsubscribe
SubscribedEmailBooleanTrue when welcome email has to be sent for any new subscriber (it works only when double optin is implemented)
BouncedEmailStringAddress for error messages
FrontendFormBooleanEnable hosted subscription forms, which you can view and edit under Settings > List settings > List Building Tools.
PublicBooleanFlag 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)
ScopeCodeIntegerselect 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)
TrackOnOpenedBooleanTrue when link tracking has to be enabled at list level
ConversionlabTrackCodeStringCode for tracking via conversionlab
LinkTrackingParametersString

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.

DisclaimerStringHeading added to the messages in the list
HeaderListUnsubscriberStringHeading "LIST-UNSUBSCRIBE" added to the messages in the list. Suggested value = "<[listunsubscribe]>,<[mailto_uns]>"
HeaderXAbuseStringHeading "X-ABUSE" added to the messages in the list. Suggested value = "Please report abuse here: http://[host]/p"

 

 

...





DescriptionCreate a new list
HTTP MethodPOST
URLhttps://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)
Expand


Code Block
{
  "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)
Expand


Code Block
{
  "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)


Expand


Code Block
languagejs
{
  "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
Anchor
deprecatedcreatelist
deprecatedcreatelist

Expand
titleDEPRECATED - Old method for creating 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. 


DescriptionCreate a new list
HTTP MethodPOST
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/User/Lists
Reference

Go to automated doc

Expand
titleClick here to learn more about request parameters

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

Field nameTypeDescription

bouncedemail

StringAddress for error messages

charset

StringText charset (see a list of Supported Charsets)

conversionlab_trackcode

StringCode for tracking via conversionlab

default_prefix

StringDefault international prefix for mobile numbers (e.g. "0039" for Italy and "001" for United States)

description

StringAdditional details about what the list is used for.

disclaimer

StringHeading added to the messages in the list

displayas

StringThis 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

StringFormat of emails to be sent with this list ("html" or "text")

frontendform

BooleanEnable hosted subscription forms, which you can view and edit under Settings > List settings > List Building Tools.

headerlistunsubscriber

StringHeading "LIST-UNSUBSCRIBE" added to the messages in the list. Suggested value = "<[listunsubscribe]>,<[mailto_uns]>"

headerxabuse

StringHeading "X-ABUSE" added to the messages in the list. Suggested value = "Please report abuse here: http://[host]/p"

kbmax

IntegerMessage size beyond which a warning is generated. Suggested value = 100

multi_optout_list

StringDetail 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

BooleanFlag 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

StringEmail address for unsubscribe notifications. Each time a recipient unsubscribes, an email will be sent to this address.

optout_type

IntegerOptout 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

BooleanFlag 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

BooleanTrue when welcome SMS has to be sent for any new subscriber on SMS channel

sendemailoptout

BooleanWhen true a "goodbye email" is sent to recipient that unsubscribe

senderfax

StringDeprecated field, do not use it

senderfaxname

StringDeprecated field, do not use it

sms_sendername

StringDefault 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

BooleanTrue when welcome email has to be sent for any new subscriber (it works only when double optin is implemented)

tracking

BooleanTrue when link tracking has to be enabled at list level

Customer

BooleanTrue if your mailing is directed to consumers

Name

StringList name (max 50 characters)

business

BooleanTrue if your mailing is directed to businesses

copyTemplate

BooleanDeprecated field. Always use "false" value

copyWebhooks

BooleanWhen true and an existing list is set as template, then webhooks configuration is copied from that list

idSettings

IntegerID of an existing list to be used as template. This field is ignored when 'useDefaultSettings=true'

scope

Stringselect 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

BooleanWhen false, an existing list, specified by 'idSettings' field, is used as template. Otherwise default settings are used
CompanyNameStringThe 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
ContactNameStringThe contact reference name
AddressStringThe company's address
CityStringThe company's city
PostalCodeStringThe company's postal code
StateOrProvinceStringThe company's state or province
CountryCodeStringThe company's country. Please use one of the Country codes provided by the method Get List of Country codes.
PhoneStringThe company's phone number
WebSiteUrlStringThe company's web site url
PermissionReminderStringUse 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
{
   "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 
Anchor
getlistdetails
getlistdetails

DescriptionUGet list details by id
HTTP MethodGET
URLhttps://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)


Expand


Code Block
languagehtml/xml
{
  "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 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
titleIt'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.


DescriptionUpdate an existing list
HTTP MethodPUT
URLhttps://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)


Expand


Code Block
languagejs
{
  "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)


Expand


Code Block
languagehtml/xml
{
  "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

Expand
titleDEPRECATED - Old API method to update an existing list


DescriptionUpdate an existing list
HTTP MethodPUT
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/User/List/{List_ID}
Reference

Go to automated doc 

 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)


Code Block
{
  "Name":"New Arrivals",
  "description":"Use this list to inform subscribers about new products",
  "IdList":2
}


JSON response (example)


Expand


Code Block
languagehtml/xml
{
   "bouncedemail" : "g1g7g@g1g7g.bounce.smtpnext.com",
   "charset" : "UTF-8",
   "conversionlab_trackcode" : "",
   "default_prefix" : "001",
   "description" : "Use this list to inform subscribers about new products",
   "disclaimer" : "<br><br><font face=\"Verdana\" size=\"1\" color=\"#666666\">Privacy Protected with <a href=\"http://b1g7g.smtpnext.com/p\" target=_blank>Safely Subscribe System</a></font>",
   "displayas" : "campo1,campo2,campo3",
   "format" : "html",
   "frontendform" : true,
   "headerlistunsubscriber" : "<[listunsubscribe]>,<[mailto_uns]>",
   "headerxabuse" : "Please report abuse here: http://[host]/p",
   "kbmax" : 100,
   "multi_optout_list" : "2",
   "multipart_text" : true,
   "nl_sendername" : "John Smith",
   "notifyemail" : null,
   "optout_type" : 0,
   "owneremail" : "john@example.com",
   "public" : true,
   "replyto" : "mary@example.com",
   "sendconfirmsms" : false,
   "sendemailoptout" : false,
   "senderfax" : "",
   "senderfaxname" : "",
   "sms_sendername" : "SMSText",
   "subscribedemail" : true,
   "tracking" : true,
   "Customer" : true,
   "IdList" : 2,
   "Name" : "New Arrivals",
   "business" : true,
   "scope" : "newsletters",
   "CompanyName": "Your company name",
   "ContactName": "Your contact reference",
   "Address": "Your address",
   "City": "Your city",
   "CountryCode": "IT",
   "PermissionReminder": "Your permission reminder",
   "Phone": "Your phone number",
   "PostalCode": "26100",
   "StateOrProvince": "Cremona",
   "WebSiteUrl": "Your site"
}



Paging and filtering (example)
 


Delete List

DescriptionDelete an existing list
HTTP MethodDELETE
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}
ReferenceGo to automated doc
JSON request (example)

To ensure your intention to delete the list, we need to know 2 list-related values:

  • put the list identifier (id_List) into the resource url
  • add the If-Match header and set its value to the ListGuid value

Code Block
languagebash
curl -X DELETE 
	 https://services.mailup.com/api/v1.1/rest/ConsoleService.svc/Console/List/{id_List}
     -H 'authorization: Bearer {access_token}'   
     -H 'if-match: {ListGuid}'


JSON response (example)
  • if list succesfully deleted

    Code Block
    empty


  • if IF-MATCH header missing

    Code Block
    403 Forbidden
    
    {
      "ErrorCode": "403",
      "ErrorDescription": "Missing If-Match header.",
      "ErrorName": "Forbidden",
      "ErrorStack": null
    }


  • if IF-MATCH contains a wrong value (i.e., if-match: aaaa)

    Code Block
    412 PreconditionFailed
     
    {
      "ErrorCode": "412",
      "ErrorDescription": "If-Match header content type must be: System.Guid.",
      "ErrorName": "PreconditionFailed",
      "ErrorStack": null
    }


  • if IF-MATCH contains a value that does not match to provided id_list

    Code Block
    412 PreconditionFailed
     
    {
      "ErrorCode": "412",
      "ErrorDescription": "Invalid [listGuid] from If-Match header field.",
      "ErrorName": "PreconditionFailed",
      "ErrorStack": null
    }


Paging and filtering (example)
 


Read Lists

DescriptionReturn 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 MethodGET
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List
ReferenceGo to automated doc
JSON request (example)none
JSON response (example)


Expand


Code Block
languagehtml/xml
{
  "IsPaginated": false,
  "Items": [
    {
      "Company": "",
      "Description": "",
      "IdList": 23,
      "ListGuid": "2bb7ad3d-6f4f-4526-b35f-aea9e912097f",
      "Name": "New Arrivals"
    },
    ...
    {
      "Company": "",
      "Description": "Iscritti alla newsletter. Si possono creare infinite liste, ad esempio per tipologie di newsletter, per società...",
      "IdList": 1,
      "ListGuid": "aafa5375-bcf1-4e06-965a-e3a98b626156",
      "Name": "Newsletter"
    }
  ],
  "PageNumber": 0,
  "PageSize": 20,
  "Skipped": 0,
  "TotalElementsCount": 6
}



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
titleDEPRECATED - Old read lists method


DescriptionReturn 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 MethodGET
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/User/Lists
ReferenceGo to automated doc
JSON request (example)none
JSON response (example)


Expand


Code Block
languagehtml/xml
{"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.


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

No Format
"StatusDescription": "Not confirmed (status: NotConfirmed)",
"StatusCode": 0

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 MethodPOST
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/TrustedSenders
 Reference

Go to automated doc

Expand
titleClick here to learn more about request parameters

Mandatory fields are marked in bold.

Field nameTypeDescription

Email

StringThe email address to be trusted



 JSON request (example)


Code Block
{
  "Email":"youremailaddress@yourdomain.eu"
}


 JSON response (example)


Code Block
{
  "AuthorizationDate": "",
  "CreationDate": "2016-11-28 12:34:36Z",
  "EmailAddress": "youremailaddress@yourdomain.eu",
  "IdTrustedSender": "ror11zuGscWcjl7m",
  "StatusCode": 0,
  "StatusDescription": "Not confirmed (status: 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 MethodGET
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/TrustedSenders
 Reference

Go to automated doc

 JSON request (example)

None

 JSON response (example)

 




Code Block
{
  "IsPaginated": false,
  "Items": [
    {
      "AuthorizationDate": "2016-09-22 16:43:55Z",
      "CreationDate": "2016-09-22 16:43:45Z",
      "EmailAddress": "youremailaddress@yourdomain.eu",
      "IdTrustedSender": "ror11zuGscWcjl7m",
      "StatusCode": 0,
      "StatusDescription": "Not confirmed (status: NotConfirmed)",
      "UpdateDate": "2016-09-22 16:43:55Z"
    }
  ],
  "PageNumber": 0,
  "PageSize": 20,
  "Skipped": 0,
  "TotalElementsCount": 4
}

The table below shows that you have to consider in your integration.

StatusCodeStatusDescriptionMeaning
0Not confirmedYou have just requested to trust an email address
1ConfirmedSender email address validated
2BlockedYou 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.

HTTP MethodGET
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/TrustedSenders/{IdTrustedSender}
 Reference

Go to automated doc

 JSON request (example)

None

 JSON response (example)

 




Code Block
{
  "AuthorizationDate": "2016-09-22 16:43:55Z",
  "CreationDate": "2016-09-22 16:43:45Z",
  "EmailAddress": "youremailaddress@yourdomain.eu",
  "IdTrustedSender": "ror11zuGscWcjl7m",
  "StatusCode": 0,
  "StatusDescription": "Not confirmed (status: NotConfirmed)",
  "UpdateDate": "2016-09-22 16:43:55Z"
}

The table below shows that you have to consider in your integration.

StatusCodeStatusDescriptionMeaning
0Not confirmedYou have just requested to trust an email address
1ConfirmedSender email address validated
2BlockedYou disable a trusted sender

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:

No Format
"StatusDescription": "Blocked (status: Blocked)",
"StatusCode": 2

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 MethodDELETE
URLhttps://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/TrustedSenders/{IdTrustedSender}
 Reference

Go to automated doc

 JSON request (example)

For security reason, you need to submit the email address to disable using the If-match header.
Mandatory header are marked in bold.

HeaderValueDescription
If-match

{EmailAddress}

The EmailAddress related to the IdTrustedSender defined in the request URL


 JSON response (example)
  • If the EmailAddress matches the IdTrustedSender

    Code Block
    200 OK
    
    {
      "AuthorizationDate": "",
      "CreationDate": "2016-11-28 12:34:36Z",
      "EmailAddress": "youremailaddress@yourdomain.eu",
      "IdTrustedSender": "ror11zuGscWcjl7m",
      "StatusCode": 2,
      "StatusDescription": "Blocked (status: Blocked)",
      "UpdateDate": "2016-11-28 12:57:30Z"
    }


  • If the If-Match header misses

    Code Block
    403 Forbidden
    
    {
      "ErrorCode": "403",
      "ErrorDescription": "Missing If-Match header.",
      "ErrorName": "Forbidden",
      "ErrorStack": ""
    }


  • If the If-Match header conatins an email address that does not match with the address identified by IdTrustedSender

    Code Block
    412 Precondition failed
    
    {
      "ErrorCode": "412",
      "ErrorDescription": "Invalid [EmailAddress] from If-Match header field.",
      "ErrorName": "PreconditionFailed",
      "ErrorStack": ""
    }
  



...

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

ReferenceGo to automated doc

JSON request (example)


Code Block
languagehtml/xml
{ "Name":"Test REST API Group", "Notes":"Notes should go here" }


JSON response (example)


Code Block
languagehtml/xml
{"Deletable":true,"Name":"Test REST API Group","Notes":"Notes should go here","idGroup":30,"idList":2}


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}

ReferenceGo to automated doc

JSON request (example)


Code Block
languagehtml/xml
{ "Name":"Test REST API Group renamed", "Notes":"I changed the notes again"}


JSON response (example)


Code Block
languagehtml/xml
{"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

Readgroups of specified list

HTTP Method

GET

URL

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{ID_LIST}/Groups

ReferenceGo to automated doc

JSON request (example)

none

JSON response (example)


Expand


Code Block
languagehtml/xml
{"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)

  • https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/2/Groups?PageNumber=0&PageSize=5

Retreive all the groups whose name exactly matches the string 'Test' using filterby="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.

  • https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/2/Groups?filterby="Name==%27Test%27"&orderby="idGroup+asc"

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}

ReferenceGo to automated doc

JSON request (example)

none

JSON response (example)

none

Paging and filtering (example)

none

...


Add recipients to a group

...

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

ReferenceGo to automated doc

JSON request (example)


Code Block
DELETE https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/1/Group/139/Recipients


JSON response (example)


Code Block
{
    "Removed": 0
}


Paging and filtering (example)

none



Tip
titleNew to MailUp?

Click here to learn more about the difference between lists and groups in MailUp.

...