Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 16 Next »

New to MailUp?

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

 

On this page:

 

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

Create List

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

Go to automated doc

 Click here to learn about available 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)

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

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

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=false'

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
JSON request (example)
 Click here to expand...
{
   "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,
}
JSON response (example)

List ID (e.g. 18)

 

Paging and filtering (example)

 

 

 

Update 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 method. In addition, the Update method also requires the IdList field.

JSON request (example)
{
  "Name":"New Arrivals",
  "description":"Use this list to inform subscribers about new products",
  "IdList":2
}
JSON response (example)
 Click here to expand...
{
   "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"
}
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/User/Lists
ReferenceGo to automated doc
JSON request (example)none
JSON response (example)
 Click here to expand...
{"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)

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

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.

  • https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/User/Lists?filterby="Name.Contains(%27Newsletter%27)"&orderby="idList+desc"

 

Add recipients to a list (subscribe)

You can use REST API to

  • add and subscribe 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)

REST API include either a method for single (refer to "Update subscription") or bulk (asynchronous import with "asOptout" option) unsubscription. 



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

JSON request (example)

{ "Name":"Test REST API Group", "Notes":"Notes should go here" }

JSON response (example)

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

Paging and filtering (example)

none

 

Update group

Description

Update a 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}

JSON request (example)

{ "Deletable":true, "Name":"Test REST API Group", "Notes":"I changed the notes again", "idGroup":30, "idList":2 }

JSON response (example)

{"Deletable":true,"Name":"Test REST API Group","Notes":"I changed the notes again","idGroup":30,"idList":2}

Paging and filtering (example)

none

 

Read Groups

Description

Read groups of specified list

HTTP Method

GET

URL

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

JSON request (example)

none

JSON response (example)

 Click here to expand...
{"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 contains 'Test' filterby="Name.Contains('Test')" and sort them by ID orderby="idGroup asc". Parameter names can be retreived from the response body. Please note that "Contains" is case sensitive.

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

 

Delete Group

Description

Delete a 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}

JSON request (example)

none

JSON response (example)

none

Paging and filtering (example)

none

 

Add recipients to a group

You can use REST API to

  • 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

REST API does not include yet a method for a bulk removal from a group, while the removal of a single recipient by specifying its ID is available. Refer to "Update group membership"

  • No labels