Uniform Mail : Parameter Reference

Notes

• Most parameters may be supplied either by url or by file.
• If you are viewing this page offline after downloading, review the files uniformmail.params and example.params.
• All parameters take the form name = value.
• 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.

maskfields = password, zipcode

ticket=bugs_geewhizz.ticket,1042

ticket=comments.ticket,0h

csvfile=formdata.csv

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

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

csvoptions=linebreak:\n, recordfieldnames:1

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

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

NEW (v 1.5)
In addition to sending data by email, data can be recorded.

• Form data must be submitted by the POST method (not GET) i.e. the body parameter cannot be used.
• All fields are written on a single line, however, if a field contains a linebreak, it will wrap onto a second line unless the csvoptions value linebreak is specified.
• The filename must be specified using the csvfile parameter.
• Fields must be specified using the csvfields parameter.
  Only specified fields are recorded.
• As a minimum, both csvfile and csvfields 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 1.5)
In addition to sending submitted form data to company email addresses, etc. and recording data in a csv file, 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. or copy_

• copy_xxx specifies a new but equivalent constant value.
• copy.xxx refers to a variable value, i.e. a submitted data field.
  If copy.xxx and copy_xxx are both specified the copy.xxx takes precedence but is ignored if the resulting value is null (i.e. the field is empty or missing).
  If no valid copy value is specified, a default is taken from the standard equivalent value.
• copy.to should normally refer to a clean email address, i.e. without a display name.
• copy.name should refer to the display name to which email will be sent.
  copy.name must be blank if the field identified by copy.to is likely to contain a display name.
• The following parameters are currently recognised :-
  copy.to, copy.name, copy.subject, copy.enable, copy_return, copy_from, copy_subject, copy_replyto, copy_mask, copy_body
• As a minimum, copy.to must 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_email              # field name specified in form (required)
  copy.name    = user_name               # field name specified in form (optional)
  copy.subject =                         # field name specified in form
  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 = Confirmation of enquiry # constant value
  copy_from    = Geewhizz Inc            # constant value. If address is omitted, copy_replyto is used. 
  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 is 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.

Examples

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

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

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.