Uniform Mail : Parameter Reference

Notes

If you are viewing this page offline after downloading, review the files uniformmail.params and example.params.

Many parameters may be supplied either by url or by file
Parameters take the form
parameter_name = value

NEW (v 2.0)

Parameters can also be specified indirectly
parameter_name* = field_name
Validation rules can also be specified by file
parameter_name /= regular_expression
parameter_name != regular_expression

When supplied as part of the url :-
parameters must be separated using &.
some characters must be encoded (see below).
Parameters supplied by file override or limit the use of url parameters.
The default file name is uniformmail.params.
If a file parameter = ! the corresponding url parameter is disabled - blank is used.
If a file parameter = * a default value is used. For addresses, * means limit to this domain.

Email addresses may be calculated by combining, url and file parameters.
If the file parameter contains '@', the url parameter is ignored.
If the file parameter omits '@' it is assumed to be simply a domain name. In this case, the corresponding url parameter must omit the domain.

e.g.	file param	: to = geewhizz.com
	url param	: to="Gee%20Whizz%20Support"<support@> (The character is optional.)
	The domain name specified in the file is combined with the partial email address specified in the url. i.e. the form data will be sent to support@geewhizz.com %20 is translated into <space>.

When email addresses are passed as url parameters, the '@' character may be replaced by '::' (double colon).
This may help to stop spambots locating email addresses in your html form pages.

Parameter

Description

params

This value must be specified by URL, there is no corresponding file parameter.

This may be used to specify an alternative file to the default of unformmail.params
If the file is not found, the default is used.

sendmail
NEW (v 2.0)

This value must be specified by file, there is no corresponding URL parameter.

The default value is 1.
If sendmail = 0 the to, cc and bcc parameters are normally ignored, however to may be used to report errors.
This value is ignored unless valid sql or csv values are specified.

mailserver

This value can be specified by URL, but for security, it should be set using a file parameter.

This must be set to the name of the smtp server.
The value localhost will work on most servers.
Other typical values are smtp.thisdomain.com, mail.thisdomain.com, or simply thisdomain.com

e.g.

mailserver = localhost

domain

This value must be specified by file, there is no corresponding URL parameter.

This may be used to limit addresses to the server's domain name.
Generally, this should be set to * to auto-detect the domain name.

referrer

This value must be specified by file, there is no corresponding URL parameter.
It may be used to limit use of the script to a single domain.

Generally, the file parameter should be ! or blank.
If specified it must be a domain name (omitting the www. prefix).
This works by checking the HTTP_REFERER value. This is sent by the browser and can be disabled. If disabled or called from another domain, the script will fail.
* may be used to represent the domain.

The following parameters are used to specify email addresses.
If a domain name is specified as the file parameter, the corresponding URL parameter must use * as the domain name.
Also see notes above.

This value is used to specify the primary recipient.

Normally, this value is ignored if sendmail = 0, however...
If an error occurs, this value may be used to report the error.

e.g.

to = * # restrict URL parameter to this domain.
to = "Support"<support@thisdomain.com>

Carbon Copy - a list of addresses to which the mail should be copied.

Entries may be separated by commas or semicolons.
Recipients of copies will see the same display name as the primary recipient.
This value is ignored entirely if sendmail = 0

e.g.

cc = fred.flintstone@bedrock.net, "Wilma"<wilma@happyhousewives.com>

bcc

Blind Carbon Copy - as cc except that the list of addresses is not added to the mail header.
Quoted display names serve no purpose but do no harm.

return

Generally, the file parameter should be !, however, if you wish to be notified of mailing errors, you may assign another value.
This MUST NOT include a quoted display name.

from

Generally this should be set to something like "Uniform Mail"<uniformmail@yourdomain.com>

replyto

Generally the file parameter should be !

Miscellaneous parameters

body

Generally, the file parameter should be !

If the file parameter is blank, the body text may be specified using the URL.
If specified by URL, linebreaks may be inserted using %0D, %0A or %0D%0A.
If specified by file, only a single line of text is allowed.
There is no indirect version - i.e. specifying body* = will have no effect.

Body text is usually set using data posted by a form.
Use of this parameter is not generally recommended but it may be useful in unusual situations.

charset
NEW (v 2.0)

Generally, the file parameter should be blank if the charset varies with different languages.

If specified

This value is inserted in the result page as a meta tag

The following headers are added to the email

Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset=UTF-8 // or whatever charset value was specified

Generally, it should match the equivalent value of the form page (or its http header).
No default is specified, partly for backward compatibilty and partly to avoid potential conflicts with server defaults.
This value can be specified in the csv_fields and sql_fields lists to ensure character encoding is saved with other data.

debug

Generally, the file parameter should be 1 when testing and either 0 or ! when testing is complete.

If debug = 1, diagnostic information is displayed. If possible, mail is still sent and/or data recorded.
If the file parameter is blank, diagnostic information may be requested using the url.

hide
NEW (v 2.0)

This value should consist of a comma-separated list of field names that should not be included in email. Typically, it should be used to filter out button values and hidden form values used to supply indirect parameters.

All fields can be recorded in a database or CSV file irrespective of this setting, however
Hidden fields are not displayed in the standard reply page even if they are recorded.
If any value contains characters that are not letters, digits or underscore, it is treated as a regular expression.
When specified by file, multiple hide statements can be used. Each will extend the list of field names to be hidden.
When specified by url, it can extend a list specified by file.

e.g.

hide = submit, button2 # don't mail button data

e.g.

hide = ^my_.*          # hide all fields that begin with my_

insert
NEW (v 2.0)

In addition to data submitted by the form, extra data fields can be inserted at the start of the output stream.

Currently, two values can be specified being ticket and datetime.
Each additional value is inserted on a new line in the specified order.
A blank line is also inserted to separate this data from the actual submitted data.
If a ticket is specified, its value is always inserted at the top of the standard reply page but it is no automatically inserted in the body of any email that is sent.

e.g.

insert = datetime, ticket

maskchar
NEW (v 2.0)

This used to specify the character used to mask out values in the reply page. The default value is '#'.

e.g.

maskchar = $

maskfields
NEW (v 2.0)

This is used to specify field names that should be masked out in the reply page.

Names are not case-sensitive and should be separated by commas.
This value has no effect on the receipt (if any) unless copy_mask = 1
Also see Copying to the Sender.

e.g.

maskfields = password, zipcode

priority

This is used to set the X-Priority: mail header.

If specified, it must be an integer in the range 1 to 5. The highest priority is 1.
The value 1 is typically displayed as an exclamation mark by email clients.
If a recipient is rejected, the priority is always set to 1 and the list of rejected recipients is appended to the body of the email.

e.g.

priority = 3

subject

This is used to specify the subject of the email.

e.g.

subject  = New User Signup

e.g. Create a subject from two data fields using indirection.

subject* = {product_name} - {product_problem}

template
NEW (v 2.0)

This is used to format the output by specifying a static html page that will be used as a wrapper for the output of the mail script.

This page must be uploaded in ascii mode otherwise it may fail with unpredictable results.
Output should validate correctly using either HTML 4.01 Strict or XHTML 1.0 Strict as the doctype, however, to correctly detect XHTML (so that <br /> is used for linebreaks) the text XHTML must exist on the first line of the template (in the doctype declaration). Loose and Transitional doctypes should also be fine, however, XHTML 1.1 is NOT recommended. In all cases the Content-Type used in the http header is text/html.
Generally, this page will be located in the cgi-bin, therefore the page should include the following :-
```
<base href="http://www.*^/contact.html">
```
The * character is automatically replaced by the domain name.
The ^ character causes this line to be moved to the top of the <head> (recommended).
The <base> tag should be located on its own line.
If a charset is specified as a parameter and also by meta tag, the value in the meta tag will be replaced.
The meta tag should be located on its own line and formatted thus...
```
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
```

The <body> of the page must include the text @@uniformmail@@.

To ensure the output is valid, it should be located in a <div>.
This whole line will be removed and replaced by the multi-line output of the mail script.
e.g.
```
<body><div>
@@uniformmail@@
</div></body></html>
```

e.g.

template = template_contact.html

ticket

This value must be specified by file, there is no corresponding URL parameter.

This is used to create ticket numbers that are placed in the subject line of the resulting email.
A filename must be specified. An initial value may also be specified following a comma.
e.g.

ticket=bugs_geewhizz.ticket,1042

will cause ticket numbers to be inserted into the subject.
The counter value is stored in the file bugs_geewhizz.ticket
The first number will be 1043.
The 21st bug report might have the following subject line:-
[#1063] GeeWhizz - bug report

The suffix h may be used to issue hexadecimal tickets.
e.g.

ticket=comments.ticket,0h

timeout

This is the maximum period, in seconds, for which the script will wait for the smtp server to respond.

The default is 20.
This may be ignored on some systems.

e.g.

timeout = 30

validate
NEW (v 2.0)

Generally, the file parameter should be 0 or 1. If blank, this value can be specified by url.

The default value is 1. This causes validation rules (if any) to be applied. Also see Validating Data.

verify

Generally the file parameter should be 0 or !

The the value 1 will cause verification of each recipient address to be requested.
Typically, smtp servers respond with the status code 252 - verification not possible.
If your server supports verification of addresses, you may find this useful in unusual situations.

NEW (v 2.0)
If verify = 2, the address is validated syntactically before being verified.
Common email addresses (that use only letters, digits, hyphen and underscore) should be fine, however, peculiar addresses with characters like = or + in the local part may be rejected (even though such characters may be considered legal).

e.g.

verify = 0 # Do not attempt verify addresses
verify = 2 # Validate and try to verify addresses

The following parameters should be used only if you wish to save data to an SQL compatible database such as MySQL.
They must be specified by file - there are no corresponding URL parameters.
If not required, they should be left blank.

sql_connect
NEW (v 2.0)

This value must consist of a string that describes how to connect to the database.
It must always begin DBI:DriverName: however, the remainder will depend on the driver and your server configuration.
Your server administrator should be able to advise you but here are some examples.
You may also experiment using the supplied additional script db_connect.pl to find the correct value.

sql_connect = DBI:mysql:my_database
sql_connect = DBI:mysql:database=my_database;host=localhost

sql_connect = DBI:CSV:f_dir=./my_database_faked_using_csv
sql_connect = DBI:Oracle:my_database
sql_connect = DBI:Informix:my_database
sql_connect = DBI:InterBase:dbname=my_database
sql_connect = DBI:Sybase:database=my_database

This value is ignored unless sql_fields is also specified.
The perl module named DBI must be installed. This is a generic database interface that requires a driver.
A database driver must be installed, e.g. DBD::mysql - different types of database require different drivers.
The installation of perl modules must normally be done by your server administrator.
The uniformmail script must be edited - remove the # on the line that reads # use DBI;
Also see Recording Data in a Database
You may use the link below to search for a driver for your database
http://search.cpan.org/search?query=DBD&mode=module

sql_fields
NEW (v 2.0)

This value is used to specify which fields are to be saved in the database.

This value is ignored unless sql_connect is also specified.
It must consist of a comma-separated list of field names.
Each name must correspond with a column in the specified table with the database, otherwise an error will occur.
If the database is case-sensitive, each name specified in this list must match a column name exactly. However, comparisons with names in submitted data is not case-sensitive i.e. the names of input boxes on the form are not case-sensitive.
New columns cannot be created, they must already exist within the database table.
The database table must be specified using sql_options.

The following field names are reserved and should not be used in forms :-

datetime	:	represents the time when the form data was submitted.
charset	:	represents the character set used as speciified by the charset parameter.
ticket	:	represents the ticket number, if any.

e.g.

sql_fields = name, age, zip

sql_options
NEW (v 2.0)

This is used to specify the table into which data is saved and other miscellaneous values.

This value is ignored unless sql_fields and sql_connect are specified.
This value must consist of a comma-separated list of name:value pairs.
Options names are not case-sensitive.

The following options are recognised.

Name	Default	Meaning
username		A valid username to access the database.
password		A valid password to access the database.
table	uniformmail	The name of the database table in which data should be stored. The table cannot be created, it must already exist within the database.

e.g.

sql_options = table:my_users, username:jimbo, password:yippee

The following parameters should be used only if you wish to save data to a CSV (comma separated values) file.
They must be specified by file - there are no corresponding URL parameters.
If not required, they should be left blank.

csv_file
NEW (v 2.0)

This value is used to specify the CSV file.

This value is ignored unless csv_fields is specified.
It should consist of a filename only.

e.g.

csv_file=formdata.csv

csv_fields
NEW (v 2.0)

This value is used to specify which fields are to be saved in the CSV file.

This value is ignored unless csv_file is specified.
It should consist of a comma-delimited list of field names corresponding with values in the form.
Field names should not contain spaces.
Field names are not case-sensitive.

The following field names are reserved and should not be used in forms :-

datetime	:	represents the time when the form data was submitted.
charset	:	represents the character set used as speciified by the charset parameter.
ticket	:	represents the ticket number, if any.

e.g.

csv_fields=datetime, ticket, name, family-name, email, zip, phone, fax

csv_options
NEW (v 2.0)

This is used to specify miscellaneous values.

This value is ignored unless csv_fields and csv_file are specified.
This value must consist of a comma-separated list of name:value pairs.
Option names are not case-sensitive.
If a value contains spaces, it must be wrapped in double-quotes.
The following options are recognised.

linebreak
If specified, linebreaks are replaced by the specified character string.
If not specified, values that contain linebreaks are wrapped in quotes and extend over multiple lines.
Linebreak:\n is treated as a special case - in addition to encoding linebreaks as '\n' all occurences of '\' are replaced by '\\'.

recordfieldnames:0/1
0 : fieldnames are not recorded in the csv file.
1 : default - field names are recorded on the first line when the file is first created.

e.g.

csv_options=linebreak:" <{ ", recordfieldnames:0

e.g.

csv_options=linebreak:\n, recordfieldnames:1

Instead of the standard results page, you can display another page.
You can change the style of the standard result page using the file uniformmail.css.
You can inject the result into a static html template.
Prior to version 1.0.1, the following parameters were simply called success and error.

url_success

This is used to specify the URL of a success page.

This value is igored if debug = 1
Generally, the file parameter should be ! to display default information.
If specified, the url must include the http://..... etc.
You may use * to represent the domain name.

e.g.

url_success=http://www.*/contact/mail-success.html

url_error

As url_success except this page is displayed if an error occurs.
Use of this parameter is not recommended since detailed error messages will not be displayed.

Validating Data

NEW (v 2.0)
Ideally, validation should be performed on-page using javascript, however, data fields can also be validated before processing.

To switch off validation, set validate = 0.
All validation rules consist of a field-name followed by /= or != followed by a regular expression (or "regex").
/= implies that a pattern match is required for successful validation.
!= implies that a pattern match must not exist for successful validation.
An error message may be added following :::
If the error message contains {braces}, it is treated like an Indirect Parameter i.e. as a composite that includes data fields.
All rules must be provided in the params file - validation rules cannot be specified by url.
Errors are reported only after all rules have been applied.
All regular expressions are passed directly to perl using the following code
$ok = ($fieldvalue =~ m/regex/i); # pattern matches are case-insensitive
The following characters have special meaning in regular expressions and must be prefixed by \ to specify the literal value.
* . ? + [ ] ( ) { } ^ $ | \
Regular expressions normally require $ to be encoded as \$ when the literal value is required, however, it is optional here if the following character is a letter.
Also # must be encoded as \# since # is normally used to insert comments in the params file.
Also, you may encode @ as \@ to avoid possible amibiguities in the perl interpreter (@@ can be problematic).

e.g.

region /= (\nengland)$  ::: only English address are accepted
email  != (\.hotmail\.) ::: hotmail addresses are not accepted

Indirect Parameters

NEW (v 2.0)
In addition to specifying parameters directly, parameters may be specified using submitted data fields. This is achieved by specifying the parameter by file and placing * after the name. The value may contain any character string but if an error occurs during subsitution, the value is ignored entirely.

e.g

subject* = [\#{ticket}] {product_name} : DELIVERY MISSED

Indirect parameters can only be specified by file.
The actual value used should normally be supplied using hidden form elements.
Field names must be wrapped in {braces}, they will be replaced by submitted values.
If no {braces} are used, the whole value is assumed to be a simple field name.
Field names must consist of letters, digits and underscore only.
If the result is invalid, it is ignored.
The result is considered invalid if the submitted data does not include the specified field name.
If you wish to insert a single { or } it must be prefixed by \.
If you wish to insert a single \ you must use \\.
If subject* is specified, the ticket value (if any) is NOT inserted into the subject automatically.
If ticket* is specified, new ticket files cannot be created - this is a deliberate security measure.

Hint

If you specify several parameters indirectly and wish those values to be hidden from the user, choose a consistent prefix for all relevant form fields, and use a single hide statement e.g.
copy_send* = cfg_want_receipt
hide = ^cfg_.*

Recording Data in a Database

NEW (v 2.0)
In addition to sending data by email, data can be recorded in a database.

The perl module named DBI must be installed.
This is a generic interface that can handle many types of database but each type requires a driver.
The script must be edited - you must remove the # on the line that reads # use DBI;
If the DBI module is not installed, an Internal Server Error is likely to result when the script is called.
The appropriate perl DBD module must be installed, e.g. DBD::mysql
This is a database driver and must be appropriate for your database.
Normally, perl modules and drivers must be installed by your server administrator, however, common modules are often already installed so this problem doesn't arise.
If you install and run the script db_connect.pl you can quickly test if necessary modules are installed - see sql_connect.
All sql parameters must be specified in the params file (not the URL).
Generally, all the relevant fields in the database should be strings (not integers, etc.) however, specific drivers may be able to perform conversions.

Recording Data in a CSV File (comma-separated-value file)

NEW (v 2.0)
In addition to sending data by email, data can be recorded in a CSV file.

All fields are written on a single line, however, if a field contains a linebreak, it will wrap onto a second line unless the csv_options value linebreak is specified.
The filename must be specified using the csv_file parameter.
Fields must be specified using the csv_fields parameter.
Only specified fields are recorded.
As a minimum, both csv_file and csv_fields must be specified otherwise all CSV instructions are ignored.
If a field is blank, it is recorded as "", i.e. two double-quotes.
If a field contains commas, semicolons, double-quotes or white space (including linebreaks) it is enclosed in double-quotes.
If a field contains double-quotes, each will be escaped with another double-quote.
e.g.
ab c"de"f gh will be recorded as "ab c""de""f gh" but smith will be recorded as smith since it contains no whitespace or special characters.

Copying to the Sender (creating a receipt)

NEW (v 2.0)
In addition to sending submitted form data to company email addresses, etc. and recording data, you can also send a receipt to the person that submitted the data (assuming they provide you with a valid email address). This requires additional parameters that can only be specified by file. The parameter names are generally the same as those above but are prefixed by copy_

The following parameters are currently recognised :-
copy_to copy_subject copy_return copy_from copy_replyto copy_body
copy_mask copy_send
Usually some values will be indirect such as copy_to.

As a minimum, copy_to* should be specified otherwise no receipt is sent.
If specified, copy_send* should be the name of a checkbox requesting a receipt.
e.g.

copy_to*     = "{user_name}"<{user_email}> # composite of two field names specified in form (required)
copy_send*   = want_receipt                # field name of checkbox requesting receipt
 
copy_return  = mailerrors@geewhizz.com # constant value : MUST NOT CONTAIN QUOTED DISPLAY NAME
copy_subject =                         # constant value
copy_from    = no-reply@geewhizz.com   # constant value
copy_replyto = no-reply@geewhizz.com   # constant value
copy_mask    = 1                       # apply maskfields value to receipt
copy_body    = Thank you for your enquiry.\nThe following information has been sent to our sales dept.+
 
# If copy_body is omitted only submitted data is sent.
# If copy_body ends with a '+' submitted data is appended beginning with a new line.
# In copy_body linebreaks are represented by '\n' but '\' should NOT be encoded as '\\'
#              but simply written as '\'.

Although it is normally fine to use a null return address for internal mail, when sending mail to users, a valid return address can be essential to avoid avoid being wrongly identified as spam.
Since some spam filters reject all mail that is not white-listed by the user (or require a captcha form to be completed by the sender) it is advisable to provide sufficient information on the form for the user to white-list your company/organisation.

Encoding Special Characters

Certain characters are not permitted in, or have special meaning in, urls and html - such characters must be encoded.

In html, characters are encoded as sequences beginning with `&´ and ending with `;´ e.g. "
In urls, characters are hex-encoded with % as a prefix e.g. %20 represents [space].
The & character is permitted in urls but not in html. Therefore, when written in html, it must be encoded as &
When constructing urls with javascript, the & character MUST NOT be encoded as &
When constructing urls with html, both encoding methods may be permissable but the %hh method is recommended.
The javascript function escape() may be used to perform url-encoding.

The following table summarizes the encoding likely to be required when constructing urls for Uniform Mail.

	HTML	Javascript
&	&	&
space	%20	%20
"	%22 or "	%22 or "
>	%3E or >	%3E or >
<	%3C or <	%3C or <

Examples

action="/cgi-bin/formmail/uniformmail.pl?from="form mail"<formmail@domain.com>&debug=1"

may be encoded for HTML as (<form> action)

action="/cgi-bin/formmail/uniformmail.pl?from=&quot;form%20mail&quot;&lt;formmail@domain.com&gt;&amp;debug=1"

or for Javascript as

action="/cgi-bin/formmail/uniformmail.pl?from=%22form%20mail%22<formmail@domain.com>&debug=1"

Only the parameter part of the url (following the `?´ character) should be encoded.
When the form action is set using javascript, simple url-encoding of the parameters is required - use the escape() function.