HTTP API Specifications

The following are get/post request that you can make to the MailUp system. On the page the word "recipient" is used to identify your customers/users/subscribers.

GET or POST?

In addition to HTTP POST, methods whose name starts with "Xml" can also be called using HTTP GET method. In this case, input parameters are expected via querystring and they must be properly encoded.

Subscribe.aspx

You can use subscribe.aspx as the form handler from a form hosted on your Web site. It allows you to offer your Web site visitors a way to sign up for your newsletter(s), while giving you full control on the look & feel of the signup form. By default the signup process uses the double opt-in method (confirmed opt-in), althuough this can be turned off as discussed below (not recommended!).

The signup form must be structured as described below:

• the field “name” attribute for each field must match the corresponding code that can be located under Settings > Codes Table and List GUID in your MailUp admin console. 
• the field "type" is entirely up to you

<form  method="post" action="http://xyzw.espsrv.com/frontend/subscribe.aspx">

Email field

REQUIRED

The form must contain a field named "email". The forms that you can create in your MailUp admin console under Settings > Signup Form contain some basic JavaScript validation to validate that a correct email address has been provided. Feel free to use that JavaScript code.

<input name="email" type="text" size="60" maxlength="100">

List fields 

REQUIRED

You must specify which list(s) the subscriber is being subscribed to. You can include more than one list, but at least one must be specified. If it's only one list, you can include it as a hidden field.

<input type="hidden" name="list" value="1"> 

If you wish to let the recipient choose more than one list (e.g. "New product announcements" and "Special offers"), you can do so by presenting them using check boxes. For example, assuming that...

• "New product announcement" is List #2 in your MailUp account
• "Special offers" is List #3 in your MailUp account

... you would have:

<input name="list" type="checkbox" value="2">New product announcements<br>
<input name="list" type="checkbox" value="3">Special offers<br> 

If you wish to subscribe a recipient to more than a list, without letting them pick, you can use the following format:

<input type="hidden" name="list" value="1,2,3"> 

The “value” field must contain the ID of the list the recipient will be subscribed to. You can see that numeric value shown in the MailUp admin console under Codes Table.

Note that even if you subscribe the new recipient to multiple lists, only one subscription confirmation request message will be sent.

• The email sent is the subscription confirmation request message of the first List included in your submission
• The recipient will be "pending" in all lists until subscription has been confirmed.
• After clicking on the link in the email, the “pending” status is converted to “subscribed” in each list that was submitted in the form action

Single vs. double opt-in

OPTIONAL 

By default MailUp always uses a double opt-in - also called confirmed opt-in (COI) - subscription process: the new subscriber must confirm their intend to subscribe. This is an email marketing best practice and the only sure way to avoid spamtraps and other potentially damaging email addresses to end up into your list(s).

We understand that there can be rare cases in which single opt-in might be preferable. Before you do so, however:

• Understand the risks involved: your sender reputation could be very negatively impacted by the presence of "bad" emails in your list
• Understand that your MailUp account could be terminated if you send a mailing to a list of recipients that contains spamtraps

To turn off COI (not recommended) and switch to a single opt-in signup process, include the following in the form code:

<input type="hidden" name="confirm" value="off" />

Mobile phone number

OPTIONAL

You can use the mobile number field to record the customer's mobile number in the database and be able to send text messages to them.

<input id="prefix" value="001" type="text" name="prefix" />
<input id="sms" type="text" name="number" />

Please note that the field “prefix” (international prefix) needs not be entered as a separate field, it can also be inserted in the field “number”. We recommend passing it as a separate field for clarity’s sake.

Groups

OPTIONAL

You can optionally present the recipient with a choice of one or more groups.

<input name="group" type="checkbox" value="1"> First group <br>
<input name="group" type="checkbox" value="2"> Second group <br> 

If you want the recipient to be subscribed to one or more groups, without presenting a choice, simply set the type as “hidden”, as in the example below:

<input name="group" type="hidden" value="2,8,10"> 

In the example above, the recipient is automatically subscribed to groups 2, 8 and 10. The Group IDs are listed in your MailUp admin console under Settings > Codes table.

Other personal data fields

OPTIONAL

You can ask your recipients to provide any other piece of information that will be saved in the Personal Data Fields that have been setup under Manage > Personal Data Fields.

<input name="campo1" type="text" size="60" maxlength="100"> First Name
<input name="campo2" type="text" size="60" maxlength="100"> Last Name

The field type is entirely up to you. The field name is based on the field ID located in the Codes Table and List GUID. 

Modifying the sender email and name

You can choose to submit as part of the customer registration the following values to override the default ones for the List.

<input type="hidden" name="dynsndmail" value="email@example.com" > 
<input type="hidden" name="dynsndname" value="Name Surname"> 

This allows to send a subscription confirmation message with a personalized sender. When both have been specified, they will be set as the values in the “From” field, while the default name and email address for the MailUp list will be used for the “Sender” field. So, on many clients this message will be viewed as “sent by Sender on behalf of From”. A confirmation email like this contains a link to the newsletter management system to complete the subscription, while, if the recipient replies to the email message (“Reply to”), the reply will be sent to the address indicated in the “From” field. This practice is very useful when a confirmation email is sent to an acquaintance: the invitation is much more effective if the person who invites is among the senders of the email (in the “From” field).

Throttling limitations

Here below the throttling limitations:

Xmlsubscribe.aspx

Usage: subscription

This call is similar to the previous one: the main differences is in the format with which the parameters are defined, and in the fact that "xmlSubscribe" returns an output code with information about the outcome of the operation, when instructed to do so.

URL

The URL to use depends on your MailUp account's unique URL. If your MailUp admin console address is xyzw.espsrv.com, the correct action URL for the form (the URL of the form handler) will be http://xyzw.espsrv.com/frontend/xmlSubscribe.aspx

REQUEST PARAMETERS

⁽¹⁾ at least one between email or sms parameters must be specified
⁽²⁾ if the prefix not specified, default settings for the list will be used
⁽³⁾ for further details on how to use these fields, please see the section about the "subscribe.aspx" API (top of this page)
⁽⁴⁾ ConfirmListID parameter is available on MailUp 8.3.1 or more recent versions 

RESPONSE VALUES

Make sure that the retCode parameter is set to 1 to receive a response code. Otherwise a text string is returned.

Code Examples

# Refer to https://mailup.atlassian.net/wiki/display/mailupapi/MailUp+RubyGem for gem information.
require 'mailup'
m = MailUp::API.new('console_url')
m.xml_subscribe(:email => 'sample@email.com', :list => 1)
# => 0

GET	https://consolehostname.org/frontend/xmlsubscribe.aspx?email=name.surname@example.com&List=1,2&Group=6,24

Get https://consolehostname.com/frontend/xmlSubscribe.aspx?list=1&Group=10&email=sample.mail@gmail.com&csvFldNames=campo1;campo2&csvFldValues=John;Doe&confirm=0&retCode=0

Xmlchksubscriber.aspx

Usage: subscription status check

This function performs a check on a recipient's subscription status 

URL

The URL to use depends on your MailUp account's unique URL. If your MailUp admin console address is xyzw.espsrv.com, the correct action URL for the form (the URL of the form handler) will be http://xyzw.espsrv.com/frontend/Xmlchksubscriber.aspx

REQUEST PARAMETERS

(1) At least one of the email or sms parameters must be specified
(2) if the country code (international prefix) is not specified, the default settings for the list will be used

RESPONSE VALUES

Code Examples

# Refer to https://mailup.atlassian.net/wiki/display/mailupapi/MailUp+RubyGem for gem information.
require 'mailup'
m = MailUp::API.new('console_url')
m.xml_chk_subscribe(:listGuid => 'abc123', :list => 1, :email => 'sample@email.com')
# => 2

Xmlunsubscribe.aspx

Usage: unsubscription

This function forces the unsubscription of a subscriber from a list.

URL

The URL to use depends on your MailUp account's unique URL. If your MailUp admin console address is xyzw.espsrv.com, the correct action URL for the form (the URL of the form handler) will be http://xyzw.espsrv.com/frontend/Xmlunsubscribe.aspx

REQUEST PARAMETERS

(1) at least one between email or sms parameters must be specified
(2) if the prefix is not specified, default settings for the list will be used

RESPONSE VALUES

Code Examples

# Refer to https://mailup.atlassian.net/wiki/display/mailupapi/MailUp+RubyGem for gem information.
require 'mailup'
m = MailUp::API.new('console_url')
m.xml_unsubscribe(:listGuid => 'abc123', :list => 1, :email => 'sample@email.com')
# => 0

XmlUpdSubscriber.aspx

Usage: recipient profile update

# Refer to https://mailup.atlassian.net/wiki/display/mailupapi/MailUp+RubyGem for gem information.
require 'mailup'
m = MailUp::API.new('console_url')
m.upd_subscriber(:listGuid => 'abc123', :list => 1, :email => 'sample@email.com')
# => 0