Creating HTML Forms for use with Tectite FormMail

Introduction

Tutorials

Learn the basics with our online tutorials:

Quick start...

The quickest way to get started is with our low-cost Configuration Wizard.

This page describes how to configure an HTML form to use Tectite FormMail. You do this by changing some tags and adding some hidden fields.

If you know nothing about HTML forms, we recommend you use our Configuration Wizard to get a working sample HTML form. You can also check out our tutorials.

Alternatively, you can download a sample form with embedded instructions here.

Communicating With FormMail

Your HTML form communicates its requirements to formmail.php through a set of "hidden" fields, using HTML tags like this:

<input type="hidden" name="..." value="..." >

The data to be processed by formmail (e.g. the actual email of form results to send to you) comes from a combination of hidden fields and other form fields (i.e. data entry fields from the user).

Configuring Your HTML Form

Here are the steps to use formmail.php with your HTML form:

Create your HTML form using standard HTML. Set the form tag's action attribute to the URL of your formmail.php.
Ensure your HTML form has the following fields defined. These are fields you expect the user to fill in:

email

the user's email address

realname

the real name of the user
Add some hidden fields to your form to tell FormMail what to do with the form results (see below). Typically, you'd specify recipients, subject, and required, as a minimum.

Once your form is working, you'd probably add good_url and bad_url.
Check that you've provided at least one of these fields:
- recipients
- logfile
- csvfile and csvcolumns
If you don't specify any of these, then formmail.php will fail because you've given it no work to do!

Hidden Fields

There's more!

This is not an exhaustive list: there are other hidden fields that FormMail recognizes for more advanced functions.

See the How-To guides for more features.

The following is a list of the hidden fields you place in your HTML form to instruct FormMail to perform various actions with form results.

recipients

a comma-separated list of email addresses that the form results will be sent to. These must be valid according to the TARGET_EMAIL configuration inside FormMail.
Example:

<input type="hidden" name="recipients"
    value="jack@mysite.com,mary@hersite.com" />

You would normally use the AT_MANGLE feature to hide the email addresses from spambots. You can also use email address aliases.
Example:

<input type="hidden" name="recipients"
    value="jackATTmysite.com,maryATThersite.com,moreinfo" />

From version 8.14 of FormMail, recipients can be an array. This allows you, for example, to use multiple-selection boxes or checkboxes to allow your users to easily select multiple recipients. For example,

<select name="recipients[]" multiple="multiple">
    <option value="jackATTmysite.com">Jack</option>
    <option value="maryATThersite.com">Mary</option>
    <option value="moreinfo">Get more information</option>
</select>

In the above examples, "moreinfo" would be an email address alias you define using EMAIL_ADDRS.

cc and bcc

a comma-separated list of email addresses that the form results will be sent to as CC ("carbon copy") and BCC ("blind carbon copy"), respectively. These must be valid according to the TARGET_EMAIL configuration inside FormMail.
Example:

<input type="hidden" name="cc"
    value="sarah@mysite.com,john@hersite.com" />
<input type="hidden" name="bcc"
    value="myemailwatcher@mysite.com" />

You would normally use the AT_MANGLE feature to hide the email addresses from spambots.
Example:

<input type="hidden" name="cc"
    value="sarahATTmysite.com,johnATThersite.com" />

From version 8.14 of FormMail, these fields can be arrays. This allows you, for example, to use multiple-selection boxes or checkboxes to allow your users to easily select multiple addresses. For example,

<select name="cc[]" multiple="multiple">
    <option value="jackATTmysite.com">Jack</option>
    <option value="maryATThersite.com">Mary</option>
</select>

required

a list of fields the user must provide, together with a friendly name. The field list is separated by commas, and you append the friendly name to the field name with a ':'.
Example:

<input type="hidden" name="required"
    value="email:Your email address,
    realname:Your name,Country,
    Reason:The reason you're interested in our product" />

Note that field names and friendly names must not contain any of these characters:

:|^!=,"

Advanced usage allows you to do the following:

field1:name1\|field2:name2	either field1 or field2 is required (both allowed, too)
field1:name1^field2:name2	either field1 or field2 is required (both not allowed)
field1:name1=field2:name2	field1's value must be the same as field2's value
field1:name1!=field2:name2	field1's value must be different from field2's value

In all the above ":name" is optional for any field.

The "required" feature is a simplified way of doing some of what the "conditions" feature can do (see below). Only use "required" or "conditions" on your HTML forms, not both. (You can use both, but the Advanced Error Handling feature works best if you only use one of them.)

conditions

a list of complex conditions, all of which must evaluate to true to allow the form submission to proceed. Conditions are a more powerful alternative to the "required" specification (see above).

We recommend that you use the "conditions" feature or the "required" feature on your HTML forms, but not both. "Required" is simpler to use, but less powerful.

The list of conditions is separated by a character you specify by the first character in the list. You specify the internal conditions component separator as the second character in the list, as follows:

<input type="hidden" name="conditions" 
    value=":@condition1:condition2:condition3" />

specifies that the conditions are separated by the colon character, and that internally, each condition's components are separated by the @ character.

There are size limitations to HTML fields. Therefore, FormMail allows you to specify any number of conditions fields like this:

<input type="hidden" name="conditions1" 
    value=":@condition1:condition2:condition3"  />
<input type="hidden" name="conditions2" 
    value=":@condition4:condition5:condition6"/>

A condition has this general format (spaces optional):

@COMMAND@ test1 @test2 @... @MESSAGE@

COMMAND and MESSAGE are mandatory. MESSAGE is the message to display to the user if the condition fails. "@" is the internal separator that you specified as the second character of the conditions list. The tests are field comparisons, and have this general format:

field1 OP field2

OP is an operand. Tests are similar to the "required" specification, but the friendly field names are not supported (or needed, because you can provide a general message).

field1	field1 must have a value
field1&field2	both field1 and field2 must have a value
field1\|field2	either field1 or field2 must have a value (both allowed, too)
field1^field2	either field1 or field2 must have a value (both not allowed)
field1=field2	field1's value must be the same as field2's value
field1!=field2	field1's value must be different from field2's value
field1~pattern	field1's value must match the specified perl regular expression
field1!~pattern	field1's value must not match the specified perl regular expression
field1#=number	field1's value is interpreted as a number and must equal the given number
field1#!=number	field1's value is interpreted as a number and must be not equal to the given number
field1#<number	field1's value is interpreted as a number and must be less than the given number
field1#>number	field1's value is interpreted as a number and must be greater than the given number
field1#<=number	field1's value is interpreted as a number and must be less than or equal to the given number
field1#>=number	field1's value is interpreted as a number and must be greater than or equal to the given number
!	the test evaluates to "false".
empty	the test evaluates to "true".

The available COMMAND values are:

@TEST@test@message@	the test must be true. If not, the given message is shown.
@IF@test1@test2@test3@message@	if test1 is true then test2 must be true. If test1 is false then test3 must be true.

Following are some examples of conditions.

`@TEST@realname@ Please provide your name so that we can address you properly.@`	Test "realname" for a value and display the given message if it has no value. This has exactly the same functionality as a required specification except that you can provide an arbitrary message.
`@TEST@email=email2@ Please enter your email twice.@`	Test that the fields "email" and "email2" have the same value.
`@TEST@age #>= 18@ You must be at least 18 to continue.@`	Tests the age the user claims to be.
`@IF@ salutation ~ /usefirst/ @ firstname@lastname@ You must provide your first name if you want us to use it to address you, or, your last name for Mr., Mrs., etc.@`	Tests that firstname is required if salutation has the value "usefirst", and lastname is required otherwise. On failure, the given message is shown.
`@IF@ payment ~ /ccard/ @ creditcard ~ /^[1-9][0-9]{12,15}$/@@ You must enter your credit card number to pay by credit card.@`	Tests that if the payment value is "ccard" then the creditcard field must begin with 1 to 9 and be followed by between 12 and 15 digits.
`<input type="hidden" name="conditions1" value=":@ @TEST@realname@ Please provide your name so that we can address you properly.@: @TEST@age #>= 18@ You must be at least 18 to continue.@: @IF@ payment ~ /ccard/ @ creditcard ~ /^[1-9][0-9]{12,15}$/@@ You must enter your credit card number to pay by credit card.@" />`	This is a complete example that simply shows a number of the above conditions joined together in one conditions field. Note that colon separating each condition.

mail_options

a list of options to control FormMail when sending email. Options are:

AlwaysList

Tectite FormMail has a feature where it automatically formats a simple contact form to look like an ordinary email. This happens when the form only contains some special fields (such as "email", "realname") and one non-special field (typically a textarea field).

When there are a number of non-special fields, FormMail formats the email as a list of lines like "field: value".

The AlwaysList option forces the one non-special field case to be formatted this second way instead of the first way.

CharSet

Allows you to set the Content-Type email header field to specify a particular charset value.

Note that, in general, the content type for the HTML page that contains your HTML form must also have this content type set in the page header. The w3.org website is the definitive guide for HTML pages.

From version 8.16 of FormMail, this setting also affects the encoding of the From and Subject header lines in the email according to the specifications of internet standards document RFC 2045.

DupHeader

Tells FormMail to duplicate some header lines in the body of the email. "To", "Cc", and "From" are the lines that are duplicated.

StartLine

If DupHeader is also specified, StartLine tells FormMail to include a "start" line like this "--START--". This feature can be used to help programs to automatically parse your emails.

Exclude

Provides a semicolon-separated list of fields to exclude from the form results email.

FromAddr

Provides an email address that will be the From address in the email sent. Some servers require a special email address to be specified before they will send email.

You can use the AT_MANGLE feature to hide the email address from spambots. You can also use an email alias from the EMAIL_ADDRS setting.

FromLineStyle

Allows you to select the style of From line you want in your email. These formats are valid according to the email header standard as specified in RFC822.

The FromLineStyle feature is available from version 8.15 of FormMail.

You can choose one of these values:

default	This is the default and the original format supplied by FormMail. The email address is followed by the name as a comment: `jack@nowhere.co (Jack Smith)`
AddrSpecName	Same as default.
NameAddrSpec	The email address is preceded by the name as a comment: `(Jack Smith) jack@nowhere.co`
RouteAddr	The email address is shown as a route address: `<jack@nowhere.co>`
QuotedNameRouteAddr	The email address is shown as a route address, preceded by the name in a quoted string: `"Jack Smith" <jack@nowhere.co>`
NameRouteAddr	The email address is shown as a route address, preceded by the name: `Jack Smith <jack@nowhere.co>`

KeepLines

Some fields, such as textareas, may contain embedded newlines. Normally, FormMail strips newlines from fields. If you specify this option, FormMail will keep the newlines.

NoEmpty

Normally, FormMail includes all fields sent from the user's browser even if they are empty. This option tells FormMail to exclude empty fields from the email it sends you.

NoPlain

If you specify HTMLTemplate, FormMail sends a MIME-formatted email.

Normally, in this case, FormMail includes a plain-text copy of the form results as well as the MIME-formatted form results.

If you specify the NoPlain option, FormMail does not include the plain-text copy.

SendMailFOption

This option is deprecated and has been replaced with the SENDMAIL_F_OPTION configuration setting.

HTMLTemplate

set to the name of the template to use for sending HTML email to the user

PlainTemplate

set to the name of the template to use for sending plain text email to the user

TemplateMissing

set to the string to use to fill in unsubmitted or empty fields in templates

Example:

<input type="hidden" name="mail_options"
    value="CharSet=UTF-8,PlainTemplate=results.txt,
    TemplateMissing=n/a,Exclude=email;realname;submit,
    FromAddr=me-ATT-mydomain.com,
    FromLineStyle=QuotedNameRouteAddr" />

derive_fields

a mechanism for deriving form fields by concatenating other form fields.
Example:

<input type="hidden" name="derive_fields"
    value="realname=firstname+lastname,
    fullphone=area.phone,
    address=street*suburb" />

Operators are:

+	concatenate with a single space between, but skip the space if the next field is empty
.	concatenate with no space between
*	concatenate with a single space between

file_names

a mechanism for naming the files uploaded by the form. By default, the files will be named with user's original file name. This feature allows you to provide different names. The same facilities are available as for derive_fields.
Example:

<input type="hidden" name="file_names"
    value="file1=order_id.%'-1'%,
    file2=order_id.%'-2'%" />

good_url

the URL to redirect to on successful processing.

bad_url

the URL to redirect to on failed processing.

this_form

the URL of the form that's submitting the data; used with intelligent bad_url processing.

good_template

a template file that FormMail can display on * successful processing.

bad_template

a template file that FormMail can display on failed processing.

template_list_sep

a string to use when expanding lists of values in templates. The default is comma. From version 8.27 of FormMail, you can specify certain HTML and other sequences to use. See TEXT_SUBS for more information.

subject

a subject line for the email that's sent to your recipients.
Example:

<input type="hidden" name="subject"
    value="Form Submission" />

env_report

a comma-separated list of environment variables you want included in the email.
Example:

<input type="hidden" name="env_report"
    value="REMOTE_HOST,REMOTE_ADDR,
    HTTP_USER_AGENT,AUTH_TYPE,REMOTE_USER" />

Note that this report is not available with HTML emails. However you can still access this information. To access this information and display it in your HTML, use the derive_fields feature.

filter

name of a filter to process the email before sending. You can encode or encrypt the email, for example.
Example:

<input type="hidden" name="filter"
    value="encode" />

filter_options

comma-separated list of options to control the filter.
Example:

<input type="hidden" name="filter_options"
    value="Attach=data.fmencoded" />

filter_fields

comma-separated list of fields to filter. The behaviour of this specification can vary slightly depending on your other specifications. Refer to our How-To guide on Filtering for more information.

filter_files

comma-separated list of file fields to filter. When your forms upload files, you can specify that the files are to be filtered.

The resulting filtered files are stored in the repository or attached to the email.

This feature is primarily designed for use with encryption filters, but works with any appropriate filter.

This feature is available from version 8.24 of FormMail.

logfile

name of a file to append activity to. Note that you must configure LOGDIR for this to work.
Example:

<input type="hidden" name="logfile"
    value="formmail.log" />

csvfile

name of the CSV database to append results to. Note that you must configure CSVDIR for this to work. You must also specify the csvcolumns field.
Example:

<input type="hidden" name="csvfile"
    value="formmail.csv" />

csvcolumns

comma-separated list of field names you want to store in the CSV database. These are the field names in your form, and the order specifies the order for storage in the CSV database.
Example:

<input type="hidden" name="csvcolumns"
    value="email,realname,Country,Reason" />

From version 8.23 of FormMail, you can also specify formatting requirements with each field. Note, however, you must set LIMITED_IMPORT to false for the following format specifiers to work. The format specifiers are:

clean the value. This means:

truncate to MAXSTRING length
strip the value of line breaks and multiple spaces
trim the value from leading and trailing white spaces

remove carriage returns from the value. This is useful for textarea fields if you're importing into Microsoft Excel, as Excel doesn't handle carriage returns very well.

force the value to be a string by making it a string formula. This is useful for string fields containing numbers (e.g. phone number fields) if you're importing into Microsoft Excel or OpenOffice Spreadsheet (and probably other spreadsheet programs). These spreadsheets interpret phone numbers (and other string fields starting with numbers) as being numbers instead of strings.

Example:

<input type="hidden" name="csvcolumns"
    value="email:c,realname:c,phone:cs,comments:r" />

autorespond

comma-separated list of specifications for the Auto Responder feature. Specifications are:

Subject	set to the subject line you want in the email sent to the user
FromAddr	set to the address you want as the From address in the email sent to the user. This would usually be your address. If you don't specify FromAddr, your server may use an inappropriate address for the sender of the email. You can use the AT_MANGLE feature to protect your email address from spambots. You can also use an email alias from the EMAIL_ADDRS setting.
FromName	set to the name you want to display in the From address in the email sent to the user. This would usually be your name. If you don't specify FromName, no name will be set in the From address. This feature was added in version 9.23 of FormMail.
HTMLTemplate	set to the name of the template to use for sending HTML email to the user
PlainTemplate	set to the name of the template to use for sending plain text email to the user
HTMLFile	set to the name of the file to use for sending a fixed message HTML email to the user
PlainFile	set to the name of the file to use for sending a fixed message plain text email to the user
TemplateMissing	set to the string to use to fill in unsubmitted fields in template

You can specify either HTMLTemplate or PlainTemplate or both. You can specify either HTMLFile or PlainFile or both. If you specify a template as well as a plain file, the plain file takes precedence and the template is ignored.

Example:

<input type="hidden" name="autorespond"
    value="Subject=Thanks for your purchase,
    HTMLTemplate=orderemail.htm" />

replyto

a comma-separated list of email addresses that will be specified in the Reply-To header of the email. According to the email standards, the Reply-To header in an email is the address to which the recipient should reply.
Many email clients and systems don't properly support Reply-To, but if you have a requirement for this feature and your email client does support it, then you can use it by specifying this hidden field.
Example:

<input type="hidden" name="replyto"
    value="sarah@mysite.com,john@hersite.com" />

You would normally use the AT_MANGLE feature to hide the email addresses from spambots.
Example:

<input type="hidden" name="replyto"
    value="sarahATTmysite.com,johnATThersite.com" />

From version 8.14 of FormMail, replyto can be an array. This allows you, for example, to use multiple-selection boxes or checkboxes to allow your users to easily select multiple addresses. For example,

<select name="replyto[]" multiple="multiple">
    <option value="jackATTmysite.com">Jack</option>
    <option value="maryATThersite.com">Mary</option>
                </option>

alert_to

email address to send errors/alerts to.
Example:

<input type="hidden" name="alert_to"
    value="webmaster@mysite.com" />

This feature is deprecated. The correct way to specify an email address for alerts is with the DEF_ALERT setting inside FormMail.