Versions Compared

Key

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

Table of Contents

Authorizing the IP

...

address

For security reasons, the APIs xmlSubscribe.aspx, xmlChkSubscriber.aspx, xmlUnSubscribe.aspx, xmlUpdSubscriber.aspx described here are subject to restrictions on the caller’s IP address.

  • The only accepted calls are those coming from IP addresses manually added in your MailUp admin console under Manage > Web Services > FrontEnd.
  • Although the system allows you to disable this restriction, we strongly recommend that you do not do so.
  • You can add an IP address to the list through the API itself: the function to be called is "WSActivation.aspx" (see WebService MailUpImport for details), and "ws_name=FrontEnd" is the parameter to be passed.

...

Using xmlSubscribe.aspx

To subscribe a user, a call - POST or GET - has to be performed to the address http://[ADMIN_CONSOLE_URL]/frontend/xmlSubscribe.aspx, where the first part of the URL is the URL of your MailUp admin console, passing the following parameters in any order:

ParameterRequiredCommentSample Value
ListYESThis is the integer that identifies the list within your MailUp account. This is not the List GUID.3
EmailYESThe recipient's email addressjohn.smith@mailup.com
GroupNOID of the group in which to insert the user25
ConfirmNOBoolean value that specifies whether to subscribe the user immediately (false) or send a confirmation request (true). It defaults to "true".true
csvFldNames NOID of the data field to be updated. Separate multiple data fields with ";". The word "Campo" means field in Italian.Campo7
csvFldValuesNOValue to be updated for the corresponding data field. Separate multiple data fields with ";". The values must be provided in the same order as the field names.John
Info
titleHow to locate the list, group, and field ID
A list of codes (e.g. list IDs, group IDs, etc.) is available under Settings > Codes table in the MailUp admin console. 

Generic code sample

Let's assume you want to subscribe the user "John Smith" to 2 lists, used for different purposes. List 1 is used for internal system messages, and list 2 for specials and promotions purposes. For List 2, you want to send a confirmation request to the recipient to ask that they confirm their desire to receive promotional messages. Here is the data for our example:

name: John Smith
e-mail: john.smith@mailup.com 
company: MyCompany Inc.
gender: M (which is the 5th data fields = CAMPO5)

To subscribe the user to these two lists, two different calls have to be performed (in this case the GET method is more convenient, as it calls the page directly, using the proper querystrings).

First Call: subscribe John Smith to List 1, without asking for a confirmation

http://[ADMIN_CONSOLE_URL]/frontend/xmlSubscribe.aspx?list=1&group=6&email=john.smith@mailup.com&confirm=false&csvFldNames=campo1;campo2;campo3;campo5&csvFldValues=John;Smith;MyCompany Inc;M

Second Call: subscribe John Smith to List 2, with confirmation

http://[ADMIN_CONSOLE_URL]/frontend/xmlSubscribe.aspx?list=2&email=john.smith@mailup.com&confirm=true&csvFldNames=campo1;campo2;campo3;campo5&csvFldValues=John;Smith;MyCompany Inc.;M
In the second case a subscription confirmation request message will be sent. You can customize it in your MailUp admin console under Settings > Confirmation request for each list under your account.

If the user clicks in the subscription link provided in the confirmation email he will be subscribed, otherwise he will remain among "Pending" users.

Return codes

xmlSubscribe.aspx returns the following values:

  • 0 : Subscription successfully completed
  • 1 : Generic error
  • 2 : Invalid address
  • 3 : User already subscribed
  • -1011: IP not registered

These values can be used in subscription procedures to differentiate the possible outcomes of the operation

Language Specific Code Samples

ASP.NET

The following code has been developed using C# language.

Code Block
languagecsharp
linenumberstrue
<script runat="server" language="C#"> 
void Subscribe() 
{ 
string retCode = "1"; // if retCode = 1 returned value is an error code, if retCode = 0 returned value is the error text 

string ret_val = SubscribeUser(retCode); 

// Once the value has been returned it is possible to decide what to do/view

// ******************************************************** 
// If retCode = 1 returned values are the following: 
// 0 : Operation completed 
// 1 : Generic error
// 2 : Invalid email address
// 3 : User already subscribed
// ******************************************************** 

switch(ret_val) 
{ 
case "0": 
// Display a message saying the user was subscribed successfully 
break; 
case "1": 
// Display a message saying the service is not accessible at the moment
break; 
case "2": 
// Display a message saying the email address in an invalid address
break; 
case "3": 
// Display a message saying that the user is already subscribed 
break; 
default: 
// Display a message saying the service is temporarily unavailable
break; 
} 


//************************************************************************** 
// If retCode = 0 error text is returned
//************************************************************************** 
// For example, the value ret_val can be associated to a Label object
} 

// This function calls the user's registration page and returns an output value 
string SubscribeUser(string retCode) 
{ 
string strEmail = Request.Params["email"]; // user's email address
string intList = Request.Params["list"]; // list ID 
string intGroup = Request.Params["group"]; // group to which to subscribe the user (optional) 
string blnConfirm = "1"; //Confirmation request
string csvFldNames = "Field1;Field2;Field3;Field4"; //Field names are taken from the Codes Table
string csvFldValues = "Name;Surname;Company;M"; //Values are assigned to the corresponding fields in the same order as csvFldNames 
string result = ""; // returned value

string url = "http://newsletter.nomedominio.tld/frontend/xmlSubscribe.aspx"; 
url += "?list=" + intList + "&group=" + intGroup + "&email=" + strEmail + "&confirm=" + blnConfirm.ToString() + "&csvFldNames=" + csvFldNames + "&csvFldValues=" + csvFldValues + "&retCode=" + retCode; 

System.Net.HttpWebRequest wreq = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(url); 
wreq.Method = "GET"; 
wreq.Timeout = 10000; 

System.Net.HttpWebResponse wr = (System.Net.HttpWebResponse)wreq.GetResponse(); 

// If the page answers correctly the return value is obtained 
if (wr.StatusCode == System.Net.HttpStatusCode.OK) 
{ 
System.IO.Stream s = wr.GetResponseStream(); 
System.Text.Encoding enc = System.Text.Encoding.GetEncoding("utf-8"); 
System.IO.StreamReader readStream = new System.IO.StreamReader( s, enc ); 

// vreturn value
result = readStream.ReadToEnd(); 
} 

return result; 
} 
</script>

 

...