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.
|
||||||||||||
sendmail NEW (v 2.0) |
This value must be specified by file, there is no corresponding URL parameter. |
||||||||||||
mailserver | This value can be specified by URL, but for security, it should be set using a file parameter.
mailserver = localhost | ||||||||||||
domain | This value must be specified by file, there is no corresponding URL parameter.
| ||||||||||||
referrer | This value must be specified by file, there is no corresponding URL parameter.
|
||||||||||||
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.
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.
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 !
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.
|
||||||||||||
debug | Generally, the file parameter should be 1 when testing and either 0 or ! when testing is complete.
|
||||||||||||
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.
hide = submit, button2 # don't mail button datae.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.
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.
maskfields = password, zipcode |
||||||||||||
priority | This is used to set the X-Priority: mail header.
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.
The <body> of the page must include the text @@uniformmail@@.
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,1042will 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.
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. NEW (v 2.0) 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. 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
|
||||||||||||
sql_fields NEW (v 2.0) |
This value is used to specify which fields are to be saved in the database.
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.
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.
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.
csv_fields=datetime, ticket, name, family-name, email, zip, phone, fax |
||||||||||||
csv_options NEW (v 2.0) |
This is used to specify miscellaneous values.
e.g. csv_options=linebreak:" <{ ", recordfieldnames:0e.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.
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).
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.
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="form%20mail"<formmail@domain.com>&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.