Overview
Here The following are the get/post request that you can send make to the MailUp system. On the page the word "recipient" is used to identify your customers/users/subscribers.
| Subscribe.aspx | Xmlsubscribe.aspx | Xmlchksubscriber.aspx | Xmlunsubscribe.aspx | XmlUpdSubscriber.aspx |
|---|---|---|---|---|
To subscribe recipients from a form. It supports:
No response is sent: the returned. The new subscriber is redirected to the subscription confirmation page.
| To subscribe recipients with an XML request that returns a XML response. It supports:
Unlike with subscribe.aspx, an XML response is returned. | To check a recipient's current subscription status. | To unsubscribe a recipient. | To update a subscriber's profile (recipient fields). |
| Toc |
|---|
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).
...
| Code Block | ||
|---|---|---|
| ||
<input type="hidden" name="list" value="1"> |
If you wish to let the user choose 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...
...
If you wish to subscribe a user to recipient to more than a list, without letting them pick, you can use the following format:
...
| Info | ||
|---|---|---|
| ||
| In case a user recipient subscribes to more than one list, the system will still only send one confirmation request message, which will allow the user recipient 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 recipient was subscribed to. |
The “value” field must contain the ID of the list the user will recipient 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.
...
You can optionally present the user with 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 user to recipient to be subscribed to one or more groups, without presenting a choice, simply set the type as “hidden”, as in the example below:
...
In the example above, the user is 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 users or customers to 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.
...
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 (
...
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.
...
Name | Mandatory? | Description |
N (1) | User Recipient's email address | |
Sms | N (1) | User Recipient's mobile number, with including the country code / international prefix (2) |
List | Y | List IDs: you can specify more than one list using comma as separator. |
Group | N | Groups to which to subscribe the user 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). |
csvFldNames | N | Personal data codes (separated by the ";" character) |
csvFldValues | N | Values related to personal data codes (separated by the ";" character) |
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 only when more list IDs are specified in "List" parameter. ConfirmListID is the ID of the list that contains the confirmation request message to be sent to pending subscribers. Confirmation request is sent if recipient is pending in at least one of the specified lists |
...
| 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 | User Recipient already subscribed |
| -1011 | IP not registered |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
GET http://consolehostname.org/frontend/xmlsubscribe.aspx?email=name.surname@example.com&List=1,2&Group=6,24 |
Xmlchksubscriber.aspx (
...
Subscription status check)
This function performs a check on a user subscription 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
...
Name | Mandatory? | Description |
ListGuid | Y | Alphanumeric code associated to a distribution list |
List | Y | List ID |
N (1) | User The recipient's email address | |
Sms | N (1) | User Recipient's mobile number, with including country code / international prefix (2) |
(1) at At least one between 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
...
CODE | DESCRIPTION |
1 | Generic error / user recipient does not subscribedexist |
2 | User Recipient subscribed (OPT-IN) |
3 | User Recipient unsubscribed (OPT-OUT) |
4 | User Recipient's subscription to be confirmed (PENDING) |
| Info | ||
|---|---|---|
| ||
|
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 (
...
Unsubscription)
This function forces the unsubscription of a subscriber from a list.
...
Name | Mandatory? | Description |
ListGuid | Y | Alphanumeric code associated to a distribution list |
List | Y | List ID |
N (1) | User Recipient's email address | |
Sms | N (1) | User Recipient's mobile number, with 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 | User Recipient unsubscribed successfully |
1 | Generic error |
3 | User Recipient unknown / already unsubscribed |
| Info |
|---|
| NOTE: If successfully unsubscribed, the user 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 (
...
Recipient profile update)
This function allows to update a userrecipient's personal dataprofile.
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 |
N (1) | User Recipient's email address | |
Sms | N (1) | User Recipient's mobile number, with including country code / international prefix (2) |
Replace | N | Parameter to enable or disable group replacement for the specified userrecipient. Accepted values: 0/1/false/true – Default value: false |
Group | N | Groups to which to subscribe the userrecipient |
csvFldNames | N | Personal data Recipient field codes (separated by the ";" character) |
csvFldValues | N | Values related to personal data codes Recipient field values (separated by the ";" character) |
(1) at At least one parameter between email or and sms parameters must be specified
(2) if the country code / international prefix is not specified, the default settings 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:
|
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 |