Form Mail Script Documentation

Thank you for your interest in our Form Mail Script. We recommend that you take some time and carefully read this documentation.

Back To Top

Introduction To Form Mail

Our Form Mail Script allows you to send information from forms on your website by e-mail to one or multiple recipients. It lets you send the e-mail as text or HTML. Furthermore it has multiple layers of security which reduce the possibility of unauthorized use. The script also provides the opportunity to log the sent messages.

Please pay attention that you upload all files to your server in text mode (ASCII mode).

The layout of the form and e-mail can be customized as you wish and you can define whether the user is redirected to a thank-you-page or gets the posted information displayed again.

It’s important that the Form Mail Script is called by a form or link from your website. For safety reasons the reference site is checked and compared with the script specifications. If the information agree the script is executed.

You can call the Form Mail Script by a direct call from a link or by an indirect call from an existing form. When calling the script directly the file "index.php" is linked directly and the default HTML and text templates (defined in "index.php") are used. The link looks like this:

Click Here To Send Mail

When calling the script indirectly it’s called by an existing form from a HTML page. This method lets you process several forms with the same script. HTML and e-mail templates as well as any other parameter for the script can be defined with the aid of hidden-form-fields in an HTML form.

With the indirect method you can continue using your existing contact forms with this script without complex changes.

The HTML template was written under the specifications of XHTML 1.0. Therefore all simple tags (<br> or <input>) contain a closing slash (<br /> or <input type=”text” name=”field” />). If you are using an existing HTML form, you do not need to add the ending slash.

You will need to put a line similar to this in your HTML.

<form action="./index.php" method="post">

Each form can use its own template. You call the template by adding a line similar to this in your HTML:

<input type="hidden" name="mail_template" value="email.tpl.txt" />

You can also send the same information to several different templates by including a line similar to this in your HTML:

<input type="hidden" name="mail_template" value="email.tpl.txt, report.tpl.txt" />

Back To Top

Set up and configuration

Attention: If you get the following error message during script execution – “Wrong or empty referrer (referring site)!“ - you have to insert into the variable “$referring_server” in the file “index.php” your server name (your domain with and without www and the IP address.

Example:

$referring_server = 'www.example.com, example.com, 192.0.34.166';

You may also get this message if your server has a firewall that stops the script from seeing the referrer. You can handle this by leaving the variable $referring_server empty. This will disable the referrer check. If you do so make sure to place your e-mail address directly in the e-mail template. This makes the script useless to spammers because e-mail can only be sent to the address in the template.

Other variables in the file “index.php”:

$script_root     This variable contains the following value by default: "./". This means that all pathes start at the script index. You can change the path if you want to integrate this script elsewhere on your web site (include).

$allow_empty_referer     Some tools on the user's side can hide the referrer (referring site) for privacy reasons, e.g. a firewall or a web browser. You can prohibit the access with an empty referrer by setting this variable to "no" or allow access by setting this variable "yes".

$language     Record here the token for the language (e.g. en for English, de for German). In the folder “languages” you can detect which languages are available

The following features are designed to prevent a third party (spammers) from abusing the script. You can combine the amount of e-mails sent with the IP address of the user.

$ip_banlist     This variable can contain IP addresses of servers that you want to exclude from your Form Mail Script. Please be careful. Different users may use the same IP address (proxy server). If you don’t want to use this feature just leave the variable empty.

$ip_address_count     Record here the amount of e-mails a user can send with the same IP address. Once this number is reached, the user will not be able to send more e-mails from your site until next time he dials into the Internet. The number 0 (null, zero) deactivates this function.

    When you use this feature the logging function is activated. This is necessary for the script to log the IP addresses. Therefore please make sure that the directory 'logs' and the file “logs/logfile.txt” must have writable permissions: chmod 777.

$ip_address_duration     With this variable you can define the timeframe for the maximum amount of e-mails sent by one user (see above). If the time frame is up the user can again send e-mails with the form.

$show_limit_errors     You can show an error message when a user reaches the maximum amount of e-mails he can send or when his IP-address is on the ban list ($ip_banlist). If you don’t want to show an error message the user is forwarded directly to the Thank-You page. No e-mail is sent.

$log_messages     This variable lets you activate or deactivate the logging function.

    If you want to use this feature please make sure that the directory 'log' and the file “log/logfile.txt” must have writable permissions: chmod 777.

$text_wrap     This variable contains the amount of characters after which the lines in the e-mails are wrapped. If no value is defined no line break will be added.

$show_error_messages     This variable is initially set to “yes”. This will let the script send you error messages during the configuration process. This will help you to install the script. After you have finished the configuration of the script you should set this variable to “off”. Do not leave the variable to “yes”. Otherwise visitors can take a view into the working of the script.

$path['logfile']     This variable contains the path to the log file.

path['templates']     This variable contains the path to the template files (HTML and text mail). The path can be relative (./templates/ or templates/) or absolute ( /usr/local/etc/httpd/.../form_mail/templates/). Please be sure to include the ending slash.

$file['default_html']     If you are calling the script directly by using a link this variable must contain the file name of the HTML template. The script will use this template automatically.

$file['default_mail']     If you are calling the script directly by using a link this variable must contain the file name of the text mail template. The script will use this template automatically.

$add_text     You can add further values, text, variables or other content to this variable. This content can then be displayed in the HTML and mail template by using markers/placeholders within curly brackets { and }.

If you want to add your own values to the variable $add_text please follow the pattern from the example entries.

 
 $add_text = array(
 
                     'txt_additional' => 'Additional',
                     'txt_more'       => 'More'
 
                   );
            

The first part of each entry is the name of the placeholder. To use the value of txt_addition in your template, place the name of the entry inside curly brackets. For example; {txt_addition}. The name of an entry must not contain white spaces or special characters. Only the underscore " _ " is allowed.

Back To Top

HTML template customization - templates/form.tpl.html

The “templates” directory contains the files that determine the layout of your page. You can use HTML and CSS to customize the layout as you wish.

If you are using a WYSIWYG editor like Dreamweaver, Frontpage or NetObjects, please make sure that the software does not make any changes by itself.

The “examples” subfolder contains additional HTML forms. You can use them as examples for creating your own forms. For example, the “alternative_form.tpl.html” template shows you how to let the visitor choose to recommend the page he has just visited, or the homepage. The “advanced_form.tpl.html” template contains examples of how to integrate checkboxes, radio buttons and select menus into your form.

The template files contain markers with { and } like: {txt_next_page}. These markers will be replaced by its counterparts from the language file “languages/language.en.inc.php”. You are free to edit that file and change the words and phrases. You are also free to replace the markers within the template files with real words, or to put those markers in other positions within the template file. You can also enhance the language file by using the given pattern.

The following placeholder is not included in the language file and should not be changed.

 
 {message}
 {fields}
 
 

Include Files

The script allows you to include files directly into the HTML template files. It makes no difference whether you want to include PHP, HTML or other text files. For example:

<INCLUDE FILENAME="header.php">

The script automatically replaces this line with the content of the file "header.php". Please pay attention that relative paths (../ etc.) start at the main directory of the script (same level as the index.php file).

If you use absolute paths (path starts with slash), the path starts at the www root folder of your web account by default. For example:

 /logs/
 /images/
 /layout/
 /layout/header.php
 /form_mail/
 /form_mail/templates/
 /form_mail/templates/form.tpl.html
 /form_mail/index.php
 

Let us suppose you want to include the file "header.php" into the file "form.tpl.html". If you use a relative path, you need to start at the same level as the file "index.php" is:

<INCLUDE FILENAME="../layout/header.php">

If you want to use an absolute path, you need to write your path starting at the www root folder:

<INCLUDE FILENAME="/layout/header.php">

You can find example files in the folder "templates/examples_includes/".

Form Fields

If there is an error, or a form field is left blank, the script will automatically enter a placeholder with the same name as the form field. That is to pre-fill the form fields so the user doesn’t have to fill in all fields another time. For example:

<input type="text" name="lastname" value="{lastname}">

You can add more fields to a form or change the existing fields of a form. Please make sure that the field names and the placeholder names do not contain white spaces, or special characters. They may have underscores ("first_name") in them.

Multiple Recipients

The script allows you to send a recommendation e-mail to an arbitrary number of recipients. The simplest way would be to add the desired number of form fields - one for each recipient e-mail - to your form.

You can select any field name (only alphanumeric and underscore), but every field name must start with the word "multiple_" (note the underscore) and end with a consecutively number "_1" (note the underscore).

In the folder "templates/examples/" you can find an example form and mail template. The HTML template file "multiple_recipientes_form.tpl.html" has been prepared for sending the recommendation e-mail to multiple recipients. The folder also contains the e-mail template file "multiple_recipients_mail.tpl.txt".

Let us suppose you want to let your visitors send e-mails to up to four recipients. If we choose, for example, the name "recipient_email" as field name, our multiple field names would be following:

 multiple_recipient_email_1 
 multiple_recipient_email_2 
 multiple_recipient_email_ 3
 multiple_recipient_email_4
 

The complete form fields would look like this:

 <input type="text" name="multiple_recipient_email_1" value="{multiple_recipient_email_1}" />
 <input type="text" name="multiple_recipient_email_2" value="{multiple_recipient_email_2}" />
 <input type="text" name="multiple_recipient_email_3" value="{multiple_recipient_email_3}" />
 <input type="text" name="multiple_recipient_email_4" value="{multiple_recipient_email_4}" />
 

The field names - surrounded by curly brackets - are automatically the template variables for the field values (value="...").

The script allows you to assign an arbitrary number of additional form fields to every recipient. Every field that starts with "multiple_" will automatically assigned to the corresponding recipient, based on the trailing number.

 <input type="text" name="multiple_vorname_4" value="{multiple_vorname_2}" />
 <input type="text" name="multiple_nachname_4" value="{multiple_nachname_4}" />
 <input type="text" name="multiple_empfaenger_email_4" value="{multiple_empfaenger_email_4}" />
 

The script uses the same e-mail template file for every recipient. The template variables (those in curly brackets) have the same name as their corresponding fields in the form template. But you need to replace the trailing numbers with a question mark. The script recognizes those variables and replaces them with correct values. For example:

To: "{multiple_first_name_?} {multiple_last_name_?}" <{multiple_email_?}>

The script uses the same mail template file for all recipients. All non-multiple field values appear in every e-mail.

Mandatory Form Fields

Every form field can be marked as a mandatory field. This means that the form will not be submitted until these fields are filled in. Enter all the field names you want to be mandatory, in a hidden form field in the template. For example:

<input type="hidden" name="required_fields" value="lastname, email, subject" />

E-mail Syntax

Like the mandatory fields you can define fields that you want to be checked to make sure they have the correct e-mail syntax. Enter all the e-mail field names you want to be checked, in a hidden form field in the template. For example:

<input type="hidden" name="email_fields" value="email_1, email_2" />

Extended Error Messages

If a required field has not been filled out by a visitor an error message will be displayed above the form fields by default.

The script allows you to display error messages right beside, above or below a form field. Moreover, the script allows you to alter the appearance of the form label. Following screenshot shows an example:

Following three variables are available:

 {required:fieldname=Error message}
 {syntax: fieldname=Error message }
 {error:fieldname=Default text||=Error message}
 
 

{required:fieldname=Error message}

Let us suppose you have a field "last_name" and you define it as required field. You can use following variable for the error message:

{required:last_name=Please enter your last name.}

In case the visitor has not filled out the field, the variable will be replaced with the error message:

Please enter your last name.

You could format the error text using CSS:

{required:last_name==<span style="font-weight:bold;color:#FF0000;">Please enter your last name.</span>}

The error text now appears in bold font and in red color:

Please enter your last name.

{syntax:fieldname=Error message}

Let us suppose you have a field "email" and you define it as e-mail syntax field. You can use following variable for the error message:

{required:email=Please enter a valid e-mail address.}

In case the visitor has not filled out the field correctly, the variable will be replaced with the error message:

Please enter a valid e-mail address.

You could format the error text using CSS:

{required:email=<span style="font-weight:bold;color:#FF0000;">Please enter a valid e-mail address.</span>}

The error text now appears in bold font and in red color:

Please enter a valid e-mail address.

{error:fieldname=Default text||=Error message}

You can use following variable, if you want to change the appearance of the form field label. Let us suppose you have a field "subject " and you define it as required field. You can use following variable in order to change the appearance of the label:

{error:subject=Subject||=<span style="color:#FF0000;">Subject</span>.}

Without an error the first part (everything before the two vertical lines - pipes) will be displayed. In case the visitor has not filled out the field, the variable will be replaced with the second part:

For a better understanding you could take a look at the example in the folder "templates/examples/".

Thank You Page

After the form has been submitted the user will be redirected to a page you can define in a hidden form field in the template. For example:

<input type="hidden" name="thanks" value="http://www.your-server.com/thanks.html" />

Please enter the whole URL including http:// and the domain name (i.e.: http://www.your-domain.com/).

If you don't define this field or leave it empty the script displays the data entered by the user.

Define HTML Template

If you are calling the script from an existing form in a HTML page, and do not want to use the default HTML file, you can define another HTML file in a hidden form field in the template. For example:

<input type="hidden" name="html_template" value="form.tpl.html" />

Define Mail Template

The mail template can be defined the same way. You can define a single mail template. For example:

<input type="hidden" name="mail_template" value="mail.tpl.txt" />

You can also define more than one mail template. Each of these templates can contain different recipients and contents. For example:

<input type="hidden" name="mail_template" value="mail.tpl.txt, mail2.tpl.txt" />

Select Menus

The script can process select menus like the following:

 <select name="" size="">
   <option value=""></option>
   <option value=""></option>
 </select>
 

An exception is multiple select menus.

How to make sure the value selected by the user appears after a new load of the form shows the following example:

 <select name="Salutation" size="2">
   <option value="Mr" {select:Salutation=Mr}>Mr</option>
   <option value="Ms" {select:Salutation=Ms}>Ms</option>
 </select>
 

The placeholder {select:Salutation=Ms} contains of the following elements. In the first position is the type of form field you are using. In this case it is a select menu (= select). After that follows a colon ( : ). In the second position is the name of the form field. In the example above that is "Salutation". After that follows an equal sign (=). At the last position is the value of the option tag (value="").

To make the selected value appear within the mail template, you need to enter the name surrounded by curly brackets {select: } in the mail template. For example:

{select:Salutation}

In case a user did not select one of the options the script removes the placeholder from the mail template.

Checkboxes

The script can process checkbox fields like the following:

<input type="checkbox" name=" " value="" />

You can make sure the value selected by the user will appear after a new load of the form. For example:

<input type="checkbox" name="Newsletter" value="Yes" {checkbox:Newsletter=Yes} />

The placeholder {checkbox:Newsletter=Yes} contains of the following elements. In the first position is the type of form field you are using. In this case it is a checkbox field (= checkbox). After that follows a colon ( : ). In the second position is the name of the form field. In the example above that is "Newsletter." After that follows an equal sign (=). In the last position is the value of the option tag (value="").

To make the selected value appear within the mail template, you need to enter the name surrounded by curly brackets {checkbox:} in the mail template. For example:

{checkbox:Newsletter}

In case a user did not select the checkbox the script removes the placeholder from the mail template.

Radio Buttons

The script can process radio button fields like the following:

<input type="radio" name=" " value="" />

You can make sure the value selected by the user appears after a new load of the form. For example:

<input type="radio" name="Salutation" value="Mr" {radiobutton:Salutation=Ms} />

The placeholder {radiobutton:Salutation=Ms} contains of the following elements. In the first position is the type of form field you are using. In this case it is a radio button field (= radiobutton). After that follows a colon ( : ). In the second position is the name of the form field. In the example above that is"Salutation". After that follows an equal sign (=). In the last position is the value of the option tag (value="").

To make the selected value appear within the mail template, you need to enter the name surrounded by curly brackets - {radiobutton:} - in the mail template. For example:

{radiobutton:Salutation}

In case a user did not select any of the radio buttons the script removes the placeholder from the mail template.

You can find examples of the above described features in the template "advanced_form.tpl.html".

Back To Top

E-mail Template Customization - templates/mail.tpl.txt

At the top of the mail template is the header data. For example:

 Recipient           To:
 Sender              From:
 Subject             Subject:
 Carbon Copy         CC:
 Blind Carbon Copy   BCC:
     

You can define the e-mail recipient within the template like this:

To: name@your-server.com

In addition, you can add several recipients with carbon copy and blind carbon copy:

 CC: name@other-server.com
 CC: chef@company.com
 BCC: secret@another_company.com

Note: You can not send more than one e-mail to one domain. If more than one e-mail is sent to a domain, only one will be received. The following example will not work:

 To: name@company.com
 CC: chef@company.com 

You can easily work around this, if you have access to mail forwarding on your server. Simply set up an e-mail address that will forward e-mail to the desired addresses. For example, you can set up an e-mail address (list@company.com). Mail sent to this address will be forwarded to the other two addresses (name@company.com and chef@company.com).

You can define the sender within the mail template. For example:

From: chef@company.com

You can also use information from the form. For example:

From: {email}

You also can add the name of the sender. In this case the name is followed by the e-mail address which stands between angle brackets.

From: {firstname} {lastname} <{email}>

Below the e-mail head area (header) must be an empty line (two line breaks). Below that line follows the mail content. You can customize the mail content as you like. If you add fields to your form, you will also need to place the name of those fields, within curly brackets, in the mail template.

Make sure that the names of the fields on your form, are identical to the names you place within the curly brackets, in your mail template.

Display all form data with one placeholder

You can display all form data with just one placeholder. Just add the following placeholder to the e-mail template:

{all_content}

In HTML e-mails you can use following variable. All form values are automatically displayed in a table.

{all_content_table}

Environment variables and server date and time

The following environment variables are provided by the Form Mail Script. To make these variables appear within an e-mail you need to place the following placeholders in your template:

{env_user_agent}     Browser software of the user (Mozilla, Netscape, Opera, Internet Explorer).

{env_remote_address}     IP-Address of the user.

{env_remote_host}     Host name of the user.

{env_year}     Year

{env_month}     Month

{env_day}     Day

{env_hour}     Hour

{env_minute}     Minutes

{env_second}     Seconds

Back To Top

The Log File - log/logfile.txt

The directory “log” and the file “logfile.txt” must be writeable (chmod 777).

Back To Top

Support

For the answers to your questions about Form Mail Script, and for the solutions to your problems with Form Mail Script, visit our support forum.

Back To Top

License Information

You can use the Form Mail Script for free. If you want to run the script without the link to STADTAUS.com you can purchase the full version online.

The full version includes free updates and upgrades.

Contact:

http://www.stadtaus.com/en/
http://www.stadtaus.com/forum/

More Scripts on STADTAUS.com:

Please visit our project MetaCollection. It is a resource for CGI and PHP related script archives.

Please also visit our project Green Polar Bear. The website contains a growing collection of Royalty Free Photographs.

Back To Top