Subscribe Form Reference

Last Updated: 26/6/2024     Tags: forms, subscribe, webform, capture, form
  • Switch Version
  • V5
  • V4

The full subscribe form reference structure is described below. For more information on what subscribe forms are, please read the Introduction To Subscribe Forms.

The action attribute of the form must be //[client].taguchimail.com/public/subscriber, where [client] is the Taguchi server name (contact Taguchi support if unknown); the method attribute must always be POST, but the name attribute may be any suitable name.

<form name="subscribe" action="//[client].taguchimail.com/public/subscriber" method="post">
</form>

Required Fields

Destination Page

The value of the dest input specifies the page URL to which the client should be redirected on successful submission of the form. If blank, form submission will return an event token which can be used to link subsequent events to the submission.

<input type="hidden" name="dest" value="" />

Error Page

The value of the err input specifies the page URL to which the client should be redirected if form submission fails. If blank, a failed form submission will redirect the client back to the origin page (as supplied by the user-agent in the Referer [sic] header).

<input type="hidden" name="err" value="" />

Email

The email field determines the email address of the saved subscriber. If a subscriber with that email address is already present in the system, the field values for that record will be updated with the submitted values.

<input type="text" name="email" value="" />

Subscribe/Unsubscribe Lists

A subscriber may be added to specific lists using one or more lists inputs. The value is the Subscriber List ID. If a subscriber is already unsubscribed from one or more of the lists, they will not be re-subscribed to those lists.

<input type="checkbox" name="lists" value="1" />
<input type="checkbox" name="lists" value="2" />

Alternatively, a subscriber can also be removed from specific lists using an unsub_lists input. The value is the Subscriber List ID. Using a value of default will globally unsubscribe the subscriber.

<input type="checkbox" name="unsub_lists" value="1" />

Subcriber Fields

Other subscriber data may be saved using the subscriber_* inputs; available fields are listed below:

<input type="text" name="subscriber_firstname" value="" />
<input type="text" name="subscriber_lastname" value="" />
<input type="text" name="subscriber_title" value="" />
<input type="text" name="subscriber_ref" value="" />
<input type="text" name="subscriber_notifications" value="" />
<input type="text" name="subscriber_extra" value="" />
<input type="text" name="subscriber_phone" value="" />
<input type="text" name="subscriber_dob" value="" />
<input type="text" name="subscriber_address" value="" />
<input type="text" name="subscriber_address2" value="" />
<input type="text" name="subscriber_address3" value="" />
<input type="text" name="subscriber_suburb" value="" />
<input type="text" name="subscriber_state" value="" />
<input type="text" name="subscriber_postcode" value="" />
<input type="text" name="subscriber_country" value="" />
<input type="text" name="subscriber_gender" value="" />

Custom Data Fields

Custom field data may be set using inputs named subscriber_custom_; a field named will be saved to the database with the specified value. If a field already present in the database is set, the existing value will be updated.

<input type="text" name="subscriber_custom_FIELDNAME" value="" />

Custom event data may be saved using inputs named annotation_; an event field named will be added to the database with the specified value. Custom event data are linked to the logged form submission event rather than the subscriber profile, meaning values are saved for each form submission and not overwritten by subsequent submissions.

<input type="text" name="annotation_FIELDNAME" value="" />

Custom field data and custom event data may be any type of input (text, select, textarea); values are saved to the database as UTF-8 encoded text with no maximum length. Subscribe forms may also submit files as values for custom field data or custom event data; the files will be saved to a publicly-accessible location on the Taguchi server (with a randomized unique filename), and the value of the custom field datum or custom event datum will contain the public URI of the file.

Any files uploaded with a .php extension will be ignored; the maximum file size is 10MB.


Optional Fields

Activity ID (Trigger)

The src input is used to cause a particular activity to be sent when the form is submitted. The value of the src is the numeric ID of the activity; if the activity is not approved, no message will be sent. The default Taguchi configuration requires the evt input to sent as an entered event e to trigger the activity.

<input type="hidden" name="src" value="" />

Campaign ID

The campaign input may be used to set the logged event's campaign ID, which will link the event to the campaign for reporting purposes. If a subscriber is created as a result of the form submission, the subscriber's campaign ID field is set to this ID.

<input type="hidden" name="campaign" value="" />

Event Type

The value of the evt input determines the event type logged by the form submission. The default Taguchi configuration event is an entered event e. If not present, the event type logged will be an update event ('up').

<input type="hidden" name="evt" value="" />

Data

The data input may be used to save additional information about the submission.

<input type="hidden" name="data" value="" />

Import ID

The import input may be used to set the import ID field of any subscribers created by this form, for reporting or segmentation purposes.

<input type="hidden" name="import" value="" />

Parent Event

The sevt input may be used to link the logged event to a previously-logged parent event, affecting reporting and field inheritance. The value of this input may be taken from an event token previously generated by TaguchiMail.

<input type="hidden" name="sevt" value="" />

List Options

The value of list option fields (see the Subscriber API documentation for more information) may be set using fields like x_option, where x is the ID of the list:

<input type="hidden" name="1_option" value="" />