User GuideDeveloper Guide
Maxemail statusxtremepush.com

Form Handler with HTML forms

As an alternative to using the Form Builder within the interface, you can use own HTML Form to submit data to Forms Handler.

You can simply take the Action URL from the Form Setup tab and use it as the action to your finished form.

The Basics

  • On the HTML form tag, set the method attribute to post, and set the action attribute to the Action URL

  • Each of the form fieldelements that you wish to submit must have their name attribute set to one of the listed Available Profile Fields.

    • You can use any of the available fields, it is not necessary to submit all elements

  • You must also specify the recipient's email address in an input element with the name attribute of email_address

  • The recipient's subscription status can also optionally be specified by submitting an input element with the name attribute of subscribed, with a boolean value: true or false

  • Other boolean-style values are also supported, but as always you should test submission and result of each possible value

  • If omitted, this will default to true, ie. the recipient is added and subscribed to the list

CAPTCHA

Using a CAPTCHA is required for Open Access forms, but also highly recommended for all forms. Maxemail uses the Google reCAPTCHA Invisible CAPTCHA.

The easy way

The simplest approach to add CAPTCHA to your form is to add Maxemail's Form Handler Javascript to the page:

<script src="https://mxm.xtremepush.com/scripts/formhandler.js" type="text/javascript"></script>

The form element must have a class called mxm-form and have the action attribute set to the Action URL

The bespoke way

Alternatively, it's possible to implement Google reCAPTCHA directly:

  • On page load, fetch the configuration values for the form
    • The Config URL can be determined from the Action URL, replacing process with config, eg:
      https://mxm.xtremepush.com/form/config/c/123/f/abc123
    • Make a JSONP request to the Config URL
    • The configuration includes a boolean value for recaptcha.enabled and a string for recaptcha.sitekey
  • If the configuration shows that CAPTCHA is enabled, Google Invisible reCAPTCHA should be loaded with the given API key, according to the official reCATPCHA documentation

🚧

reCAPTCHA API key

In order for Maxemail to validate the CAPTCHA response, you must implement Google reCAPTCHA using the correct API key for the form.

The API key must not be hard-coded, and instead loaded dynamically, to allow it to be updated without impacting your form.

Auto-population

If you are using a Closed Access form, or if you simply want to pre-populate form fields with values that are already known about the recipient, it's possible to enable auto-population.

  • Add Maxemail's Form Handler Javascript to the page:
    https://mxm.xtremepush.com/scripts/formhandler.js
  • Add a class to the form element called mxm-form-populate
  • Link to the form with two query-string parameters, recipient_id and email_address
    • Eg: recipient_id=123&[email protected]
    • The values can be automatically inserted from an Email using the following tokens in your link:
      recipient_id=[recipient:Recipient Identifier]&email_address=[recipient:Email Address]