Hosted Forms

Default Forms

Intilery provides four default forms related to managing subscription preferences.

These defaults are:

  1. 'unsubscribe' - A page that asks if the customer wants to unsubscribe.
  2. 'optin' - A page that subscribes the customer
  3. 'optout' - A page that unsubscribes the customer
  4. 'unsubscribed' - A page that the user is directed to after unsubscribing,

informing them that they have been unsubscribed

The content of these forms can be edited through the Campaigns > Hosted Forms screen.

Variation by Customer Property

You can also create different versions of these forms based on the variation of a customer property, for example, customer language. This will allow you to automatically link to forms of appropriate language etc. from your email campaigns. Do this by selecting a property to vary from the dropdown above the list of forms, selecting the variation you wish to overwrite the forms for and then editing the forms in the list. The edited version will apply only to the selected variation.

Adding Parameters

To add a parameter to the URL when a customer clicks on a hosted form you must use "&" instead of "?" to start your query parameters.

This is because the system adds parameters by default, which makes the parameters you add to your hosted form a continuation of this.



Custom Forms

In addition to these four default forms, you can create forms of your own using the Add New Form button and fill out the following fields:

Field Explanation
Form Path The id of your form, also the value used in the merge tag (which must be in lower case with no spaces, no hyphens) referring to this form (see Merge Tags)
Form Name A display name for your form that will appear in the UI
Form Description A description of the purpose of your form that will appear in the UI
Form Redirect Select an existing form for this form to redirect to (if applicable) when submitted (e.g. unsubscribe redirects to unsubscribed)
Markup HTML mark-up for your form. You can leave this blank and add it later in edit if you wish

These custom forms can be edited or deleted (note: the default forms cannot be deleted) using the options provided. 

Building A Working Form

Preparation and Necessities

On a form, an html form tag with the method POST must be used (an action is not needed), and the 'emailReference' value must be submitted with any form values:

<input type="hidden" name="emailReference" value="*|EMAIL_REFERENCE|*">

Once a form has been submitted the user will be redirected to the page specified (if one is set).

Customer Property Values

Customer properties can be included in the form by placing the name of the property in a merge tag with all whitespace replaced with underscores e.g.


Any customer property value can be updated using input tags that get submitted within a form tag. The name attribute on the input tag references the customer property name. There is no need to place 'customer.' before as this is prepended by the system. Reference example below for updating the users first name:

<input type="text" name="First Name">

Updating Customer.subscribed status

To give the user an option to unsubscribe themselves from the mailing list you can use the following submit button:

<button type="submit" id="unsubscribeButton" name="unsubscribe" value="on">UNSUBSCRIBE</button>

Using Subscription Categories

  • Ensure that these customer properties are of type - 'Campaign Subscription Status' in the model
  • Configure each subscription properties via the 'Campaigns'>'Subscription Categories'. Here we can add a description and a 'Subscription by Default' boolean to each.
  • In the unsubscribe form these grouped subscription customer properties can be dynamically listed using the following code as an example:

The following example will list all subscription categories and allow the user to check a box for each category to indicate if they wish to be subscribed to it or not.



            <input type="checkbox" id="subscribe-§§" name="subscribe-§§" checked>
            <input type="checkbox" id="subscribe-§§" name="subscribe-§§"> 
}§ §endif§

N.B. If all check boxes are de-selected and the form is submitted the users 'overall' subscribed status and customer property will be set to false. If any check boxes is selected and the form is submitted the users 'overall' subscribed status and customer property will be set to true.

If instead of listing all categories, you wish to show a specific category, you must hard code the information and use the category's id (found on the Subscription Categories page) in the id of the subscribe checkbox. For an example category called "My Category" with id = 57348bdbd4c68672f3f2bae4:

        My Category

        A Subscription Category I have created

            <input type="checkbox" id="subscribe-57348bdbd4c68672f3f2bae4" name="subscribe-57348bdbd4c68672f3f2bae4" checked>  
            <input type="checkbox" id="subscribe-57348bdbd4c68672f3f2bae4" name="subscribe-57348bdbd4c68672f3f2bae4"> 

Using Preferences Only (No Subscription Categories):

Note that if you have no option to set categories in the form, it will be treated the same as the user having not checked any boxes and would therefore mark the user as unsubscribed, even if they have not explicitly unsubscribed (see N.B. above).

To prevent this behaviour, if you are not giving the user any option to update subscription categories on the form (using it only for the customer to update properties), then you should include the following hidden input within the form to signal that the user subscribe status should not be changed automatically.

<input type="hidden" name="ignoreCategories" value="on" />

If you are providing the user with an unsubscribe button as above, the user will still be able to explicitly unsubscribe using the button.

Using Boolean Customer Properties

To update boolean customer properties you must begin the name attribute with "customer-<propertyName>" e.g. name="customer-sms_subscribed".

Our system will then take the first value that is passed and set the property value to this, any values after this will be ignored.

Due to checkboxes passing no value when unchecked we must explicitly send false. 

If the checkbox is checked then send true first and false afterwards as the second value is ignored.

  <label><input type="checkbox" name="customer-sms_subscribed" value="true" checked />SMS Subscribed</label>
  <input type="hidden" name="customer-sms_subscribed" value="false" />
  <label><input type="checkbox" name="customer-sms_subscribed" value="true" />SMS Subscribed</label>
  <input type="hidden" name="customer-sms_subscribed" value="false" />

Sign Up Forms (e.g. for hosting on Facebook)

A sign up form can be created for hosting or linking to from elsewhere. (e.g. by using HTML Static to link to the page in Facebook)

Ensure that the form is marked as a sign up form:

<input type="hidden" name="_formType" value="signup">

The form needs to have an email address for the user to enter to allow them to subscribe:

	<input type="text" id="email" name="email" value="*|EMAIL|*">

Custom error messages can be added to the form for error types 'NO_EMAIL' and 'INVALID_EMAIL'. For example, in the form below the messages 'Didn't match' and 'Nothing entered' will appear after the error message.

§if(ERROR.NO_EMAIL)§ Please provide and email address §endif§   

§if(ERROR.INVALID_EMAIL)§ We can't read that email address §endif§

You can include different subscription categories or other Customer properties by including form inputs that match the name to the Customer property:

	<p><input type="text" id="first name" name="first name" value="*|FIRST NAME|*"></p>

	<p><input type="checkbox" name="Newsletter" checked>Receive Newsletter emails</p>

Using SMS Unsubscribe forms

SMS unsubscribes do no require the use of the Email Reference field as seen above. Instead the form must be defined with the following attribute(s):

<input type="hidden" name="_formType" value="smsunsubscribe">

The form should also submit the two fields, one for customer email and one for customer mobile. If the mobile number matches the one on record for that customer email in the Intilery system then Customer.SMS Subscribed will be set to false

	<input type="text" id="mobile" name="mobile" contenteditable="true" value="*|MOBILE|*">
	<input type="text" id="email" name="email" contenteditable="true" value="*|EMAIL|*">

Custom error messages can be added to the form for error types 'SMS_UNSUB_MISMATCH' and 'SMS_MISSING_INFO'. For example, in the form below the messages 'Didn't match' and 'Nothing entered' will appear after the error message.

<input type="email" name="email" value="*|EMAIL|*"> Mobile: 

<input type="tel" name="mobile" value="*|MOBILE|*"> 

<a href="#" id="unsubscribe-submit" onclick="document.getElementById('unsub-form').submit();">unsubscribe me</a> 


§if(ERROR.SMS_UNSUB_MISMATCH)§ Didn't match §endif§ 

§if(ERROR.SMS_MISSING_INFO)§ Nothing Entered §endif§

Still need help? Contact Us Contact Us