How to Use formmail.pl

Shared

VPS

Dedicated

formmail.pl

We use a special version of formmail.pl. This version protects against abuse by ensuring the email recipient is legitimate.

Any form fields included in the call to formmail.pl will be included in the email that is sent.
formmail.pl has many optional hidden fields, but only the recipient field is required since it determines where the email is sent.

formmail.pl accepts form submissions using the POST method. A line of code is required to pass the form input from your page to formmail.pl. This code varies based on your hosting account type and the type of CGI used.

To ensure proper delivery of formmail, you may need to enable SPF on your domain. Some popular email providers, such as Gmail, automatically reject email without SPF enabled. 

See Turning on the Pre-Configured SPF Record for information about setting up SPF on your domain.

If you have a Dedicated or VPS account without FastCGI or a Shared Hosting account created before June 1, 2011

If your account fits into any of the following categories, follow the instructions below:

• Shared Hosting accounts created before June 1, 2011
• Dedicated accounts not using FastCGI
• VPS accounts not using FastCGI

If one of these categories describes your account, add this code to your webpage:

<form method="post" action="/cgi-sys/formmail.pl">

If your account does not fit any categories above...

If your account does not fit into the categories above, your account will likely fall into one of these categories.

• Shared Hosting accounts created after June 1, 2011
• Dedicated accounts using FastCGI
• VPS accounts using FastCGI
• Any account with cgi-sys disabled
• Domains using suEXEC or php-cgiwrap

If so, follow the instructions below:

1. Copy the formmail.pl script from the /usr/www/cgi-bin/ directory into your domain's cgi-bin folder.
2. Once you have done this, add this line of code to your webpage:

   <form method="post" action="/cgi-bin/formmail.pl">

There are no modifications needed to this line in your code.
Unless you are running suEXEC as well, you should not copy the formmail.pl file to your account's cgi-bin unless you intend on customizing the source code of it. The "cgi-bin" portion of the action above directs the server to look into the server's cgi-bin so the formmail.pl script doesn't need to reside in your individual account.

Create a file named ".formmail" in your account's home directory (/usr/home/USERNAME). Add all form recipient email addresses into this file. This will prevent the form from being abused to send to arbitrary addresses.

formmail.pl Example

In the following example, only the recipient field is required. This field specifies the destination email address for the form contents.

Example:

<input type="hidden" name="recipient" value="[email protected]">

If you wish to have multiple recipient email addresses, then separate each email address with a comma in the value section of this field.

For the following:
- Shared hosting accounts created after June 2011
- Email addresses not hosted on Pair servers

You will need to create a file named .formmail and place it into your account home directory (/usr/home/USERNAME). This prevents the form from being abused to send to arbitrary addresses.

If the form's recipient address is not hosted by Pair Networks, you will receive the following error message.

Error: Bad Recipient

formmail.pl Fields

Here are other fields you can use with formmail.pl.

subject	This field specifies the Subject line of the outgoing email. If not given, the default Subject is "WWW Form Submission."
email	This hidden field specifies the return email address. It is recommended that this email address matches the domain the form is hosted on. Example: [email protected] If not supplied, the default is [email protected].    Note: Popular email providers, like Gmail, are enforcing SPF checks on incoming email. It is recommended to enable SPF on your domain. See Turning on the Pre-Configured SPF Record for more information.
realname	This field specifies the real name of the user submitting the form. If supplied, this should be a field filled in by the user. The email will be generated with this name in the headers.
redirect	This field specifies the URL to which the user should be automatically redirected after successful delivery of the form. It must be a full URL; relative links will not work. If this field is not specified, a default response will be generated by the script.
required	This field allows you to specify that certain fields (in a comma separated list) in the form are "required." This means that these fields may not be empty when the form is submitted. If any of the specified fields are empty, the user will receive a warning, and the form will not be submitted.
title	This field specifies the title for the default response page that is generated by the script in absence of a redirect field. The default is "Thank You."
return_link_url	This field specifies a URL that will appear on the default response page that is generated by the script in absence of a redirect field. This URL can be used to allow users to return to, for example, your homepage.