Versions Compared

Key

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

...

This is an example of using the Get / Post API to subscribe a user to one or more lists in your MailUp account. For detailed specifications on using Get / Post requests to communicate with MailUp, click here.

Toc

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 httpaddress HTTP://<MailUP Admin Console URL>[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:

Group : Id
Parameter
  • List : list ID* (Mandatory)
  • RequiredCommentSample 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
    GroupNOThe ID of the group in which to insert the user
    * (Optional)
  • Email : recipient's email address (Mandatory)
  • Confirm : boolean value which
    25
    ConfirmNOBoolean value that specifies whether to subscribe the user
    at once (0
    immediately ("false" or "0") or send a confirmation request ("true" or "1
    ) (optional – default : 1)
  • csvFldNames : code list of the personal data fields to be updated, separated by the ";" character* (optional)
  • csvFldValues : values linked to the personal data fields to be updated, separated by the ";" character and
    "). It defaults to "true".true
    csvFldNames NOThe ID of the data field is 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
    fields specified in the parameter "csvFldNames" (Optional)
    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 SampleYou may

    code sample

    Let's assume you want to subscribe the user "John Smith to a "General list" in group 1 without asking for a confirmation, and to list 2 sending a confirmation request" 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:  smith@myprovider.com john.smith@mailup.com 
    company: MyCompany Inc.
    gender: M (which is the 5th data 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).The necessary codes are

    displayed in the codes table: 1 for "General list", 8 for "List 2", 6 for group 1 in the general list. The codes for personal data fields are: Campo1, Campo2, Campo3, Campo5(Name, Surname, Company, Gender). So the calls will have to be structured like this:First Call: subscribe John Smith to List 1, without asking for a confirmation

    http://
    newsletter.domainname.tld
    [ADMIN_CONSOLE_URL]/frontend/xmlSubscribe.aspx?list=1&group=6&email=
    smith@myprovider
    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://
    newsletter.domainname.tld
    [ADMIN_CONSOLE_URL]/frontend/xmlSubscribe.aspx?list=
    8
    2&email=
    smith@myprovider
    john.smith@mailup.com&confirm=true&csvFldNames=campo1;campo2;campo3;campo5&csvFldValues=John;Smith;MyCompany Inc.;M
    In the second case, a subscription confirmation
    email will be created, freely customizable at the page Settings > Confirmation request. Choose the appropriate list at the page Settings > Codes table in the administration console
    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 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
    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>

     


    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
    languagevb
    linenumberstrue
    collapsetrue
    <%@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 
    
    %>

    ...


    None  Edit Labels