Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.aspxXmlsubscribe.aspxXmlchksubscriber.aspxXmlunsubscribe.aspxXmlUpdSubscriber.aspx

To subscribe recipients from a form. It supports:

  • Multiple lists

  • Multiple groups

No response is sent: the returned. The new subscriber is redirected to the subscription confirmation page.
This can be a page you define in the List settings. (or redirected to a page of your choosing).

 

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

  • Multiple lists
  • Multiple groups
To check

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

Table of Contents

Subscribe.aspx

...

Code Block
languagehtml/xml
<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
titleMultiple lists and confirmation requests
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
languagehtml/xml
<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

Email

(1)

User Recipient's email address

Sms

(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.
In case of more lists and if you don't specify ConfirmListID(4) value, a confirmation request message will be sent for each specified list.
Otherwise, when there are more lists and ConfirmListID is specified with a valid list ID value, a single email message can be used to confirm subscription to all the lists that are specified with "List" parameter.

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

...

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

...

Code Block
languagehtml/xml
titleHTTP GET (multi list and multi group)
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

Email

(1)

User The recipient's email address

Sms

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

NOTE: Code
Info
titleImportant notes
  • 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
  • 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
languageruby
titleRuby
# 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

Email

(1)

User Recipient's email address

Sms

(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
languageruby
titleRuby
# 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

Email

(1)

User Recipient's email address

Sms

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

  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

Code Block
languageruby
titleRuby
# 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