Overview

Here are the get/post request that you can send to MailUp

Subscribe.aspxXmlsubscribe.aspxXmlchksubscriber.aspxXmlunsubscribe.aspxXmlUpdSubscriber.aspx

To subscribe recipients from a form. It supports:

  • Multiple lists
  • Multiple groups

No response is sent: the new subscriber is redirected to the subscription confirmation page.
This can be a page you define in the List settings.

To subscribe recipients with an XML request that returns a XML response. It supports:

  • Multiple lists
  • Multiple groups
To check a recipient's current subscription statusTo unsubscribe a recipientTo update a subscriber's profile

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

The signup form must be structured as described below:

Subscription form action

The URL to put in the action of the form tag 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/subscribe.aspx.

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

The parameters for calling subscribe.aspx are described below.

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 field(s) (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 user 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...

... 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 user to more than a list, without letting them pick, you can use the following format:

<input type="hidden" name="list" value="1,2,3"> 
In case a user subscribes to more than one list, the system will still only send one confirmation request message, which will allow the user to confirm their subscription to all the lists included in the signup request. Note that the system will use the message templates (e.g. subscription confirmation request message and subscription confirmation message), as well as the Web page templates defined for the first List that the user was subscribed to.

The “value” field must contain the ID of the list the user will be subscribed to. You can see that numeric value shown in the MailUp admin console under Settings > Edit lists or looking at the dropdown menu at the top left of the page. In the image, the list called "New products" has value=3.

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 user 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 user 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 user 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 users or customers 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).

Xmlsubscribe.aspx (User subscription)

This function 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. If you wish to create a form that subscribes the user to more than one list at the same time, and sends only one confirmation email, use the "subscribe.aspx" API described above.

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

Name

Mandatory?

Description

Email

(1)

User email address

Sms

(1)

User mobile number, with international prefix (2)

List

Y

List IDs (you can specify more than one list using comma as separator. One confirmation request will be sent for each specified list

Group

N

Groups to which to subscribe the user (comma separated)

Confirm

N

Parameter to enable ("1" or "true") or disable ("0" or "false") the confirmation request email. Default value: 1 (i.e. double opt-in enabled by default).

csvFldNames

N

Personal data codes (separated by the ";" character)

csvFldValues

N

Values related to personal data codes (separated by the ";" character)

retCode

N

Parameter to enable or disable the return of an output code for the call. Accepted values: 0/1 – Default value: 0

Dynsndmail(3)

N

"dynamic sender e-mail address" Sender address in the confirmation request email (If blank, default value for the list will be used)

dynsndname(3)

N

"dynamic sender name" Sender name in the confirmation request email (If blank, default value for the list will be used)


(1) at least one between email or sms parameters must be specified
(2) if the prefix not specified, default settings for the list will be used
(3) for further details on how to use these fields, please see the section about the "subscribe.aspx" API (top of this page)

RESPONSE VALUES

CODEDESCRIPTION
0Operation completed successfully / Either email address or mobile number has been changed
1Generic error
2Invalid email address or mobile number
3User already subscribed
-1011IP not registered

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	http://consolehostname.org/frontend/xmlsubscribe.aspx?email=name.surname@example.com&List=1,2&Group=6,24

Xmlchksubscriber.aspx (User subscription check)

This function performs a check on a user 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

Name

Mandatory?

Description

ListGuid

Y

Alphanumeric code associated to a distribution list

List

Y

List ID

Email

(1)

User email address

Sms

(1)

User mobile number, with international prefix (2)


(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

DESCRIPTION

1

Generic error / user not subscribed

2

User subscribed (OPT-IN)

3

User unsubscribed (OPT-OUT)

4

User subscription to be confirmed (PENDING)

NOTE: Code 1 is given as output value both in case of error (e.g. when ListGuid code does not match ListID) and when the user is not a subscribed user.

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 (User 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

Name

Mandatory?

Description

ListGuid

Y

Alphanumeric code associated to a distribution list

List

Y

List ID

Email

(1)

User email address

Sms

(1)

User mobile number, with international prefix (2)


(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

DESCRIPTION

0

User unsubscribed successfully

1

Generic error

3

User unknown / already unsubscribed

NOTE: If successfully unsubscribed, the user will be moved to unsubscribers and will receive an unsubscription confirmation email, if this option has been selected

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 (User update)

This function allows to update a user's personal data.

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/xmlUpdSubscriber.aspx

REQUEST PARAMETERS

Name

Mandatory?

Description

ListGuid

Y

Alphanumeric code associated to a distribution list

List

Y

List ID

Email

(1)

User email address

Sms

(1)

User mobile number, with international prefix (2)

Replace

N

Parameter to enable or disable group replacement for the specified user. Accepted values: 0/1/false/true – Default value: false

Group

N

Groups to which to subscribe the user

csvFldNames

N

Personal data codes (separated by the ";" character)

csvFldValues

N

Values related to personal data codes (separated by the ";" character)


(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

DESCRIPTION

0

Data updated successfully

1

Generic error

xmlUpdSubscriber.aspx returns error code = 1 ("generic error") in the following cases:

  1. List ID parameter cannot be converted into a number
  2. GUID parameter has not a valid format
  3. Specified email address does not exist in subscribers list (we recommend use of xmlChkSubscriber.aspx to check presence of email address before updating)
  4. Field csvFldValues contains a semicolon (;) character in this case we have a different number of fields in csvFldNames and csvFldNames parameters
  5. Field csvFldValues contains a ‘—‘ (two hyphen-minus characters)
  6. A temporary internal error occurred (retry later or contact us if this problem persists)
  7. Personal data of a specific subscriber is corrupted and the problem occurs only with that recipient (please contact us)

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.upd_subscriber(:listGuid => 'abc123', :list => 1, :email => 'sample@email.com')
# => 0