...
This is an example of using the Get / Post API to subscribe a user to one or more lists in your MailUp account. For details detailed specifications on using Get / Post requests to communicate with MailUp, click here.
...
To subscribe a user, a call - POST or GET - has to be performed to the address httpaddress 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:
Parameter | Required | Comment | Sample Value |
---|---|---|---|
List | YES | This is the integer that identifies the list within your MailUp account. This is not the List GUID. | 3 |
YES | The recipient's email address | john.smith@mailup.com | |
Group | NO | The ID of the group in which to insert the user | 25 |
Confirm | NO | Boolean value that specifies whether to subscribe the user immediately ("false" or "0") or send a confirmation request ("true" or "1"). It defaults to "true". | true |
csvFldNames | NO | The ID of the data field is to be updated. Separate multiple data fields with ";". The word "Campo" means field in Italian. | Campo7 |
csvFldValues | NO | Value 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 | ||
---|---|---|
| ||
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 is 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 field = 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 querystringsquery strings).
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
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 the C# language.
Code Block | ||||
---|---|---|---|---|
| ||||
<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> |
Classic ASP 3.0
In case the customer's portal has its own subscription forms, linked to other databases (e.g. to register to a database, to access a restricted area, to authenticate a user…) it is possible to add to the page code the following code, which allows to simultaneously record the data also within the MailUp console, with or without confirmation request.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<%@LANGUAGE="VBSCRIPT"%> <% on error resume next Dim strEmail, intList, intGroup Dim xml, url, response_val strEmail=request("email") ' user's email address intList=request("list") ' list ID intGroup=request("group") ' group to which to subscribe the user (optional) blnConfirm = 1 'Confirmation request csvFldNames = "Field1;Field2;Field3;Field4" 'Field names are taken from the Codes Table csvFldValues = "Name;Surname;Company;M" 'Values are assigned to the corresponding fields in the same order as csvFldNames retCode = 1 'if retCode = 1 the value returned by the request is an error code, if retCode = 0 error text is returned 'The page that will be called on our servers url="http://newsletter.domainname.tld/frontend/xmlSubscribe.aspx " ' XMLHTTP version 3.0: Set xml = Server.CreateObject("MSXML2.ServerXMLHTTP") xml.Open "POST",url,false ' Request is sent xml.setRequestHeader "Content-Type", "application/x-www-form-urlencoded" xml.Send "email=" & strEmail & "&list=" & intList & "&group=" & intGroup & "&confirm=" & blnConfirm & "&csvFldNames=" & csvFldNames& "&csvFldValues=" & csvFldValues & "&retCode=" & retCode 'If retCode = 1 returned values are the following: 'Returned values: '0 : Operation completed '1 : Generic error '2 : Invalid address '3 : User already subscribed if err.number=0 then 'Value returned by the call response_val=xml.responseText Set xml = Nothing else 'The call was unsuccessful (e.g. Network error). response_val=1 Set xml=nothing end if ' Once the value has been returned it is possible to decide what to do/view Select Case response_val Case "0" 'Display a message saying the user was subscribed successfully '... Case "1" 'Display a message saying the service is not accessible at the moment '... Case "2" 'Display a message saying the email address in an invalid address '... Case "3" 'Display a message saying that the user is already subscribed Case Else 'Display a message saying the service is temporarily unavailable End Select 'If retCode = 0 error text is returned ' Returned value is retrieved response_val=xml.responseText Set xml = Nothing %> |
...