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:
Code Block |
---|
|
<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:
Code Block |
---|
|
<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
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:
Code Block |
---|
<input type="hidden" name="confirm" value="off" /> |
Mobile phone number
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.
Code Block |
---|
|
<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
You can optionally present the recipient with a choice of one or more groups.
Code Block |
---|
|
<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:
Code Block |
---|
|
<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
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.
Code Block |
---|
|
<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.
Code Block |
---|
|
<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:
| Day | Hour | Minute |
---|
/frontend/xmlsubscribe.aspx | 20000 | 5000 | 300 |
/frontend/subscribe.aspx | 20000 | 5000 | 300 |
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
Name | Mandatory? | Description |
Email | N (1) | Recipient's email address |
Sms | N (1) | Recipient's mobile number, including the country code / international prefix (2) |
List | Y | List IDs: you can specify more than one list using comma as separator. In case of multiple lists and Confirm=1 (true), it is strongly recommended to provide a valid value for the ConfirmListID(4) parameter. This practice allows you to handle a multi list subscription using a single confirmation request message. If the ConfirmListId argument is not valued, an individual confirmation request message will be sent for each specified list. Please note that sending multiple confirmation messages, e.g. more than 10, may result into longer execution times. |
Group | N | Groups to which to subscribe the recipient (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). The notes in the "subscribe.aspx" section above under "Single vs. double opt-in (optional)" apply here as well. Turning off confirmed opt-in is very risky. |
csvFldNames | N | Personal data codes (separated by the ";" character). The field name is based on the field ID located in the Codes Table and List GUID. |
csvFldValues | N | Values related to personal data codes (separated by the ";" character) NOTE: characters that are not included in 7-bit ASCII have to be encoded (e.g. Mail&Up becomes Mail%26Up) |
retCode | N | Set it to 1 to receive a response code instead of a text string. It defaults to 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) |
ConfirmListID(4) | N | To be used when subscribing the recipient to multiple lists (more than one list IDs are specified in "List" parameter) if you want the recipient to receive only one request for subscription confirmation (e.g. they sign up for "Specials", "Promotions" and "New arrivals", but only receive one subscription confirmation request email). - ConfirmListID is the ID of the list that contains the subscription confirmation request message that you wish to send to pending subscribers.
- A click in the link contained in the confirmation request message will confirm subscription in all lists submitted with the form.
- Confirmation request is sent if recipient is pending in at least one of the specified lists.
|
source | N | Optional field that can be used to inform MailUp platform that a call to xmlsubscribe.aspx is coming from a specific application/website. When developing an integration, please make sure this type of tracking is compatible with the guidelines of the application you are connecting to MailUp (e.g. in some cases you cannot transfer source details without user's informed consent). Example: some plugins are using source=generic by default and source=application-name or source=host-name only when plugin admin user accepts to provide source data |
(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)
(4) 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 | DESCRIPTION |
---|
0 | Operation completed successfully / Either email address or mobile number has been changed |
1 | Generic error |
2 | Invalid email address or mobile number |
3 | Recipient already subscribed |
-1011 | Client IP not registered on the "Developer's corner > Web services" (select "Frontend" in the "Web services" drop-down menu). You should add the IP address (recommended choice) or you may disable IP check |
Code Examples
Code Block |
---|
|
# 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 |
Code Block |
---|
language | html/xml |
---|
title | HTTP GET (multi list and multi group) |
---|
|
GET https://consolehostname.org/frontend/xmlsubscribe.aspx?email=name.surname@example.com&List=1,2&Group=6,24 |
Code Block |
---|
language | xml |
---|
title | HTTP GET (with two fields user) |
---|
|
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
Name | Mandatory? | Description |
ListGuid | Y | Alphanumeric code associated to a distribution list |
List | Y | List ID |
Email | N (1) | The recipient's email address |
Sms | N (1) | Recipient's mobile number, including country code / international prefix (2) |
(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 | DESCRIPTION |
1 | Generic error / recipient does not exist |
2 | Recipient subscribed (OPT-IN) |
3 | Recipient unsubscribed (OPT-OUT) |
4 | Recipient's subscription to be confirmed (PENDING) |
Info |
---|
|
- Code 1 is given as output value both in case of error (e.g. when ListGuid code does not match ListID) and when the recipient does not exist in that List.
- Code 4 applies when a double opt-in subscription method is used (or Confirmed Opt-in, COI), and the recipient has not yet confirmed their subscription. COI is the default subscription method in MailUp.
|
Code Examples
Code Block |
---|
|
# 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
Name | Mandatory? | Description |
ListGuid | Y | Alphanumeric code associated to a distribution list |
List | Y | List ID |
Email | N (1) | Recipient's email address |
Sms | N (1) | Recipient's mobile number, including country code / 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 | Recipient unsubscribed successfully |
1 | Generic error |
3 | Recipient unknown / already unsubscribed |
Info |
---|
NOTE: If successfully unsubscribed, the recipient will be moved to unsubscribers and will receive an unsubscription confirmation email, if this option has been selected (NOT an email marketing best practice). |
Code Examples
Code Block |
---|
|
# 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
This function allows to update a recipient's profile.
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 | N (1) | Recipient's email address |
Sms | N (1) | Recipient's mobile number, including country code / international prefix (2) |
Replace | N | Parameter to enable or disable group replacement for the specified recipient. Accepted values: 0/1/false/true – Default value: false |
Group | N | Groups to which to subscribe the recipient (separated by the ";" character) |
csvFldNames | N | Recipient field codes (separated by the ";" character) |
csvFldValues | N | Recipient field values (separated by the ";" character) |
(1) At least one parameter between email and sms must be specified
(2) if the country code / international prefix is not specified, the default setting for the list will be used
RESPONSE VALUES
CODE | DESCRIPTION |
0 | Data updated successfully |
1 | Generic error |
Info |
---|
xmlUpdSubscriber.aspx returns error code = 1 ("generic error") in the following cases: - List ID parameter cannot be converted into a number
- GUID parameter has not a valid format
- Specified email address does not exist in subscribers list (we recommend use of xmlChkSubscriber.aspx to check presence of email address before updating)
- Field csvFldValues contains a semicolon (;) character in this case we have a different number of fields in csvFldNames and csvFldNames parameters
- Field csvFldValues contains a ‘—‘ (two hyphen-minus characters)
- A temporary internal error occurred (retry later or contact us if this problem persists)
- Personal data of a specific subscriber is corrupted and the problem occurs only with that recipient (please contact us)
|
Code Examples
Code Block |
---|
|
# 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 |