POST Handler

This chapter documents the HTTP POST form handler for implementing your own custom HTML forms on your website.

Introduction

Using the HTTP POST form handler, you can subscribe and unsubscribe users to your newsletters in a very easy way. You will do all the configuration with regards to redirection in hidden fields of the POST request.

Form fields

These are the required form fields you will need for the request to succeed:

Name Description
action Must be either subscribe or unsubscribe
email_address The e-mail address of the subscriber to be either subscribed or unsubscribed
lists A comma-separated list of Maillist IDs which the request deals with.

Subscriber data fields

If you need to save data fields along with the subscriptions, you must send additional fields named after the data field keys prefixed with data_. E.g: data_Name.

Multiple choice

If you need to supply multiple options for a single data field value, repeat the input field with the same name.

Example HTML forms

Below is some simple examples of HTTP POST forms. Care must be taken to examine the errors parameter by the server (either server-side og client-side using javascript).

Subscribe

This form will subscribe the user to lists 1 and 2 and update the subscriber data with Name and the multiple choice data field Interests:

<!-- Example HTML form -->

<form action="https://account.clients.ubivox.com/handlers/post/" method="post">

  <input type="hidden" name="action" value="subscribe" />
  <input type="hidden" name="lists" value="1,2" />

  <p>
    <label for="email_address_id">E-mail address</label>
    <input type="text" name="email_address" id="email_address_id" />;
  </p>

  <p>

    <!-- Example single text input field -->

    <label for="data_Name_id">Name</label>
    <input type="text" name="data_Name" id="data_Name_id" />;

  </p>

  <p>

    <!-- Example multiple choice field -->

    <label>Interests</label><br>

    <input type="checkbox" name="data_Interests" value="Music" id="data_Interests_0_id" />
    <label for="data_Interests_0_id">Music</label><br>

    <input type="checkbox" name="data_Interests" value="Food" id="data_Interests_0_id" />
    <label for="data_Interests_0_id">Food</label><br>

    <input type="checkbox" name="data_Interests" value="Sports" id="data_Interests_0_id" />
    <label for="data_Interests_0_id">Sports</label><br>

  </p>

  <p>
    <input type="submit" value="Subscribe" />
  </p>

</form>

Unsubscribe

This form will unsubscribe the user from lists 1 and 2:

<!-- Example HTML form -->

<form action="https://account.clients.ubivox.com/handlers/post/" method="post">

  <input type="hidden" name="action" value="unsubscribe" />
  <input type="hidden" name="lists" value="1,2" />

  <p>
    <label for="email_address_id">E-mail address</label>
    <input type="text" name="email_address" id="email_address_id" />;
  </p>

  <p>
    <input type="submit" value="Unsubscribe" />
  </p>

</form>

Your own status pages

If you want to use your own status pages instead of the standard ones, you can send the following two parameters as hidden fields in your form:

  • success_url
    The URL to which the system will redirect the user after a successful operation
  • failure_url
    The URL to which the system will redirect the user after a failed operation. (See Error handling below)

Error handling

The form system operates with two kinds of errors. Fatal errors and normal errors. Fatal errors should only occur during the development and testing of your forms. These errors will halt the subscription process and produce an error message on your screen. These consists of:

  • Missing ‘action’ parameter.
  • Missing ‘lists’ parameter.
  • Missing ‘email_address’ parameter.
  • Unknown data key.
  • Uknown mailing list.
  • Opt-in not configured yet.

The other set of errors is errors that requires the end user to take action. If you use your own failure_url status page, any errors occurred during the handling process, will be sent to the page as a set of HTTP GET parameter called errors (textual representation) and error_codes (numerical error codes) - both separated by ;.

If you haven’t configured your own status page, the system will use a set of standard templates to present the user with error messages and choices. Currently, these are the normal errors that can occur:

  • Missing required data key (Error code: 10)
  • E-mail address is already subscribed (Error code: 11)
  • E-mail address is not valid (Error code: 12)
  • Unknown E-mail address (Error code: 13)
  • E-mail address was not subscribed (Error code: 14)
  • E-mail address on stop list (Error code: 15)

Note

You should always rely on the error code and not use the textual representations for anything other than debugging. Otherwise you may risk leaving your system open for XSS or phising attacks.

Example parameters for custom error pages

Here is an example using custom error pages:

<input type="hidden" name="success_url" value="http://www.example.com/ok/" />
<input type="hidden" name="failure_url" value="http://www.example.com/error/" />

Internationalization

All messages and notifications when using the HTTP POST handler, can be internationalized to suit the language of your website. We currently support these languages:

  • da: Danish
  • de: German
  • en: English
  • es: Spanish
  • fr: French
  • it: Italian
  • nb: Norwegian
  • nl: Dutch
  • sv: Swedish

The language code must be inserted as a hidden field in your HTML form called language_code. Example:

<input type="hidden" name="language_code" value="es" />

If no language code is given, The system will try to determine the users preferred language depending on their web browser settings.

Opt-in scheme

In special circumstances it might be required that the system does not send the confirmation e-mail to new subscribers. To use this feature, approval from your support team is required.

Warning

Having a public web form with no confirmation for new subscriptions leaves you open to subscription bombing with a certain loss of reputation for your sending identity and possibly your company name.

Controlling the confirmation e-mail is done using the optin_scheme form field.

Double

To use double opt-in (with confirmation e-mail):

<input type="hidden" name="optin_scheme" value="double" />

This is the default and recommended behaviour.

Single

To use single opt-in (no confirmation e-mail)

<input type="hidden" name="optin_scheme" value="single" />

This option requires prior approval from your support team.