Uniform Mail : Parameter Reference

Notes


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.
to 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>
cc

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.
    tableuniformmail 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.

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

Hint


Recording Data in a Database

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


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.


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_


Encoding Special Characters

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

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

  HTML Javascript
& &amp; &
space %20 %20
" %22 or &quot; %22 or "
> %3E or &gt; %3E or >
< %3C or &lt; %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"