The “Quick Subscribe/Unsubscribe” Process

From Enterprise Help
This is the approved revision of this page, as well as being the most recent.
Jump to: navigation, search

Fishbowl customers who wish to host their own HTML "subscribe", "update profile" and/or "unsubscribe" pages, either instead of or in addition to the Enterprise-generated Member Pages, can do so using the Quick Subscribe/Unsubscribe process, which is available for use at Fishbowl's discretion. Please contact Fishbowl Client Support before implementing this process.

The Quick Subscribe/Unsubscribe process can be used either "client-side"—in which the user's browser makes an HTTP request by submitting an HTML form hosted on your website—or "server-side"—in which application code running on your server makes an HTTP request to the Quick Subscribe page. If you're planning on using the process server-side, please refer to the additional notes at the bottom of this page.

To use the Quick Subscribe/Unsubscribe, you'll need to create (or modify) an HTML form page on your Web site. The HTML page must contain a <form> element matching the following syntax (case-insensitive unless your Web site conforms to the XHTML standard):


<form action="http://yourhostname.fbmta.com/members/subscribe.aspx" method="POST">
....
</form>


The URL in the example above must be modified to reference your Enterprise-supplied domain name (such as "mainstreetgrill.fbmta.com"). To determine the appropriate domain name from within Enterprise, navigate to the Profile Fields page and click on the "Preview your Member Subscribe page" hyperlink. The address bar in your browser window will contain the domain name.

The example above uses the HTTP POST method, which is the normal method of passing form data from one HTML page to another. It is also possible, however, to use the HTTP GET method, in which form data is passed within the URL itself, rather than within HTTP headers. To use the GET method, simply change the word "POST" in the example above to "GET".

Within your HTML form, you must include the following input controls:

  • EmailAddress - An blank input control to contain the e-mail address of the Member to subscribe, unsubscribe, add, or update. This control should be limited to 200 characters, either by use of the "maxlength" attribute, or by Javascript validation. The format of this address MUST BE VALIDATED by client-side Javascript, as in the example below, to avoid redirecting your Members to an unbranded HTML error page. If a Member with the supplied e-mail address already exists within your Enterprise Site, then the subscribe, unsubscribe, and/or profile field update actions will target that Member. For actions other than update, if no Member with the supplied e-mail address exists within your Enterprise Site, a new Member will be added, and the value of the Action parameter (see below) will determine whether or not the new Member will be subscribed to the specified List.
  • SiteGUID - The unique identifier which distinguishes your Enterprise Site from that of other Enterprise Sites. This value can be supplied to you by Fishbowl Client Support. You should use a hidden input control ("<input type='hidden'>") to store this value.
  • ListID - A single integer value, or multiple comma-separated integer values, identifying the List(s) from which the Member should be subscribed or unsubscribed. These values can also be found on the List screen (from which you make changes to an existing List). You should use a hidden input control to store this value. A ListID parameter is not required when the form action is update. If no ListID parameter is supplied and the form action is unsubscribe, the e-mail address will be unsubscribed from all lists in the Enterprise Site. If no ListID parameter is supplied and the form action is subscribe, the e-mail address will be subscribed to all active lists in the Enterprise Site.
  • StoreCode – This field is required for SMS Clients. A string value representing the member’s favorite store. You should use a hidden input control to store the value.
  • PhoneNumber – This field is required for SMS Clients. The name of this value has to be the same as the profile field for the client listed below. This is a text input control that contains the member’s phone number. Javascript validation is required in order to ensure the correct formatting for the phone number.
  • Zip – This field is required for SMS Clients. A text input control that contains the member’s zip code. This requires javascript validation in order to ensure correct format and number of digits.
  • VibesMobileOptin – This is required for SMS Clients. It is a checkbox control that stores a member’s explicit consent to be sent marketing SMS messages.
  • ReturnURL - The (optional) absolute URL of a page on your Web site to which the Member should be redirected after the subscribe, update or unsubscribe action occurs. This page should contain some sort of "Thank you for subscribing", "Your profile has been updated" or "Thank you for unsubscribing" message. Unless an error occurs, Members will see no visual indication that they left your Web site and then were redirected back again. You should use a hidden input control to store this value.


If no ReturnURL value is supplied, the Member will—upon successful submission of the quick subscribe form—be redirected to an Enterprise-hosted page displaying the Site- or Theme-specific HTML Header and Footer and content dependent on the form action:


Action="Unsubscribe"
If one or more ListID(s) is included, the Unsubscribe (Single List) Success Message will be displayed after the form is submitted. If no ListID is included, the Unsubscribe (All Lists) Success Message will be displayed after the form is submitted.


Action="Subscribe"
If a new member submits the form, the selected Thanks Message/URL option will be displayed after the form is submitted. If an existing member submits the form, the Thanks Message OR the RedirectURL will be displayed after the form is submitted. If the Site- or Theme-specific setting uses the Redirect to Update Profile Page option in the Thanks Message/URL setting, the Thanks Message will be displayed, as we cannot redirect to an Update profile page with member information on it for security reasons.


Action="Update"
If a member who does not exist in the Enterprise site submits the form, the member will be redirected to the Subscribe page where they can join the Site as a new member. (A new member record will never be created when the Action="Update" on the form.) If an existing member submits the form, Thanks Message OR the RedirectURL will be displayed after the form is submitted. If the Site- or Theme-specific setting uses the Redirect to Update Profile Page option in the Thanks Message/URL, setting the Thanks Message will be displayed, as we cannot redirect to an Update profile page with member information on it for security reasons.


Action="SubscribeWithRespect"
If a new member submits the form, the selected Thanks Message/URL option will be displayed after the form is submitted. If an existing member submits the form, the Thanks Message OR the RedirectURL will be displayed after the form is submitted. If the Site- or Theme-specific setting uses the Redirect to Update Profile Page option in the Thanks Message/URL setting, the Thanks Message will be displayed, as we cannot redirect to an Update profile page with member information on it for security reasons.


In some of these contexts merge codes are not supported; therefore, if your default Site settings for these messages contain merge codes, you should create Theme-specific versions of these messages that do not contain merge codes.


  • SuppressConfirmation - An optional value indicating whether or not to send an e-mail notification to the affected Member. A value of "yes", "true", or "1" (case-insensitive) will cause Enterprise to NOT send such a notification. Omitting this input control, or setting its value to anything other than "yes", "true", or "1" will cause Enterprise to send the notification. You should use a hidden input control to store this value.
  • Action - An optional value indicating whether the desired action is a subscribe, update, or unsubscribe.
A value of "Subscribe" (case-insensitive) will cause Enterprise to treat the form post as a subscribe request.
A value of "SubscribeWithRespect" will cause Enterprise to treat the form post as a subscribe for new members, but any existing members will not have their subscription status modified by the request. Any profile information provided for existing members will be updated.
A value of "Unsubscribe" will cause Enterprise to treat the form post as an unsubscribe request. Omitting the action input control will cause Enterprise to treat the form post as a subscribe request. You should use a hidden input control to store this value.
A value of "Update" will update any profile information provided for existing members. If members who do not exist in the Enterprise site submit this form, the email address and other profile information posted will be ignored and not saved in Enterprise.
  • TagsToAssign and TagsToUnassign - Optional values representing the IDs or Names of Tags to assign or unassign. Tag ID values, which can be copied from the rightmost column on the Manage Tags screen, are generally a better option than Tag Names for this purpose, because names can be changed whereas ID values cannot. Multiple IDs and/or Names can be specified, separated by commas. ID or Name values that don't match and existing Tags in your site will be silently ignored.
  • _Theme - If you've instructed Enterprise to send a confirmation e-mail to the affected Member (see "SuppressConfirmation", above), and you'd like that confirmation e-mail to use Theme-specific settings, then set this optional value to the name or ID value (as shown on the Manage Themes screen) of the appropriate Theme.
The name of a Theme can change, but the ID value cannot, so using the ID value rather than the name is recommended. Note the required underscore at the beginning of the name of this input control. You should use a hidden input control to store this value.
  • EmailAddressParameter - If you'd like Enterprise to pass the e-mail address of the subscribing or unsubscribing Member to the redirect page (see "ReturnURL", above) in the query-string portion of the URL, assign this optional value to be the name of the appropriate query-string parameter.
For example, if the ReturnURL value is "http://www.fishbowl.com", the EmailAddressParameterValue is "Email", and the subscriber's e-mail address is "postmaster@fishbowl.com", then Enterprise will (upon successful submission) redirect the subscriber to "http://www.fishbowl.com?Email=postmaster%40fishbowl.com".
  • Optional Profile Fields - When subscribing Members, you can optionally include input controls corresponding to any of your existing Enterprise profile fields. If, for instance, you have a profile field named "FirstName", you can include an HTML input control named "FirstName"; Enterprise will recognize that the submitted form field has the same name as one of your profile fields and will set the Member's "FirstName" value accordingly.
Text-type profile fields (Text, TextArea, DropDown, US_Zip_Code, and US_Phone_Number), can be assigned any value, but all except TextArea fields are limited to 100 characters (you should validate accordingly, or use the "maxlength" attribute). Integer-type profile fields can be assigned only an integer value. Date-type profile fields (US_Date, International_Date, and COPPA_Compliancy) can be assigned date values in a wide variety of formats; International_Date fields will be interpreted as dd/mm/yyyy, whereas US_Date will be interpreted as mm/dd/yyyy. Checkbox-type profile fields can be assigned values of either "true" or "false" (case-insensitive). Under most circumstances, input controls of this type should be visible; hidden controls can be used, however, when appropriate.


If an existing member submits a Quick Subscribe form using the default action or an action of subscribe or update, their existing member record will be updated with any data provided. You can prevent Enterprise from overwriting existing member profile data by modifying the optional profile fields on your Quick Subscribe form. Including two preceding and two trailing underscores around a profile field name will set that profile field value for any existing members who do not have that field populated, but existing members with that profile field already populated will NOT have the field overwritten. Including one preceding and one trailing underscore around a profile field name will NEVER set that profile field value for any existing members, even existing members who do not have a value in that profile field.

The following HTML can be used as a prototype for building your own HTML subscribe/unsubscribe page. The Javascript function ("validateEmail") for validating the format of the submitted e-mail address is especially helpful because it uses the same algorithm as Enterprise itself. Before using the supplied HTML, you will need to modify some of the included input control values—as indicated in the comments below and the descriptions above—and remove all the commented text (i.e., text between ):


<!DOCTYPE HTML>
<html>
        <head>
        <title>Quick Subscribe Example</title>
        <script language="Javascript" type="text/javascript">
        function validateEmail(emailAddress)
        {
            /* NOTE: This regular expression is identical to the one used by Enterprise for e-mail address validation */
            var regExp =  /^\s*[a-zA-Z\d][a-zA-Z\d\.!#$%&'*+\-\/=?^_`{|}~]*@([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,6}\s*$/;
            if (emailAddress.length <= 200 && regExp.test(emailAddress)) {
            return true;
                        } else {
                           alert("Invalid e-mail address");
                           return false;
                                          }
        }

function validatePhone(MobilePhone)
{
     var PhoneNumber = /^\(?([0-9]{3})\)?[-]?([0-9]{3})[-]?([0-9]{4})$/;
     if(PhoneNumber.test(MobilePhone))
     {
       return true;
       }  else  {
               alert("Invalid Phone Number");  
               return false;
               }
      }

        </script>
        </head>

        <body>
        <form action="http://yourhostname.fbmta.com/members/subscribe.aspx" method="post" onSubmit="return validateEmail(this.EmailAddress.value) && validatePhone(this.Phone.value);">
          <input type="hidden" name="Action" id="Action" value="subscribe" size="30" maxlength="200">
          <!-- EmailAddress must not be greater than 200 characters -->
          <input type="text" name="EmailAddress" id="EmailAddress" value="Enter your e-mail address" size="30" maxlength="200">
          <!-- Mobile phone mandatory for SMS Clients: Has to match profile field, Requires validation  -->
          <input type="text" name="MobilePhone" id="Phone" value="Enter your Mobile Phone" maxlength="20">
          <!—- Member Zip Code: Requires Validation -->
          <input type="text" name="Zip" id="Zip" value="Enter your Zip Code" maxlength="10">
          <!—- Explicit member approval for SMS -->
          <input type="checkbox" name="SMSOptIn"><label>I would like to receive test messages with offers and updates.</label>
          <!—- Store code associated with a member -->
          <input type="text" name="StoreCode" id="StoreCode" value="001" >
          <!--  Set 'w' or 'web' as the input source -->
          <input type="hidden" name="_InputSource_" value="w">
          <!-- ListID(s) can be found on the Manage Lists page in Enterprise -->
          <input type="hidden" name="ListID" value="957293,950223">
          <!-- SiteGUID will be supplied by Fishbowl Client Support -->
          <input type="hidden" name="SiteGUID" value="12345678-90ab-cdef-1234-567890abcdef">
          <!-- ReturnURL is the absolute URL of a Web page to which the user will be redirected after submitting the form -->
          <input type="hidden" name="ReturnURL" value="http://yourdomainname/yourconfirmationpage">
          <!--SuppressConfirmation should be set to "true" or "yes" if Enterprise should NOT send a confirmation e-mail to the subscriber notifying him or her of the subscription/profile update; omitting SuppressConfirmation has the same effect as explicitly setting a value of "false" or "no" -->
          <input type="hidden" name="SuppressConfirmation" value="yes">
          <input name="Submit" type="submit" value="Submit">
        </form>
</body>
</html>



Notes on using the Quick Subscribe/Unsubscribe process "server-side":

If you're planning on calling the Quick Subscribe page from application code (PHP, .NET, Java, etc.) running on your servers, then the "ReturnUrl" parameter (see above) will have no relevance, as your code will determine the redirect behavior (if any). Instead, you should check the HTTP status code returned by the Fishbowl servers: a value of 302 (along with a corresponding "Location" header) indicates that the Quick Subscribe/Unsubscribe call was successful; any other value, such as 200, indicates an error.


In the case of a successful Quick Subscribe/Unsubscribe call, the Fishbowl server will return two HTTP response headers, "MemberID" and "NewMember". The "MemeberID" header will have a value of the unique Enterprise MemberID. The "NewMember" header will have a value of either "True" or "False", depending on whether or not the supplied email address already exists in your Site. The "NewMember" header does not indicate subscription status; in other words, a value of "False" will indicate that a Member already exists, even if that Member is not subscribed to any Lists, or has permanently bounced. If you'd like to check whether a Member already exists in the system, without adding that Member in case they don't exist, set the "Action" parameter (see above) to "Update" and supply no profile information other than email address.
Retrieved from "http://enterprisehelp.fishbowl.com/index.php?title=The_“Quick_Subscribe/Unsubscribe”_Process&oldid=1146"