FORMBOUND USER GUIDE Copyright (C) 2009 Jonathan Cullifer. INTRO Thank you for choosing Formbound. Formbound was the first of a new generation form mailer and a pioneer in template-based e-mail. It makes scripts such as formmail.cgi obsolete. The main problem with generic scripts such as formmail.cgi is that all of the data for the form, such as the subject and the receipient, is included in the HTML forms. These forms are easily modified, making the scripts an easy target for spammers. Formbound uses a set of templates to control the appearance of the mailout. It's simple, yet it's very flexible. It has capabilities far greater than any of its peers. Most importantly, however, it's secure when used correctly. INSTALLATION To begin using FormBound, simply upload the script to your server and create a subdirectory called "mailforms". All of your templates will go in that directory. CONFIGURATION FormBound only has two configuration options, both configurable by editing the header section of formbound.php. The first configuration directive allows you to specify an alternative path for mail forms. It should be a subdirectory in the same location as formbound.php, but feel free to rename it. The second is a composer form used for testing templates. It's off by default, and it should stay off except for template testing. FORMBOUND TEMPLATES Formbound templates are structured like a raw mail messages. The mail headers such as From, To, and Subject are supported, as well as any other standard mail header (except date). Formbound has its own special headers that are used to dictate how each template should behave. Take a look at the sample template to see how the template is laid out. The standard date header is automatically filled in by Formbound. Do not specify it in your templates. SPECIAL HEADER EXAMPLES Autoresponder: autoresponder.txt Processes the autoresponder.txt file as a Formbound template and mail it. This is useful for sending confirmation e-mails. Checkboxes: FIELD1,FIELD2 Assume FIELD1 and FIELD2 are checkboxes. In the template, specify them as %{CHECK_FIELD1} and %{CHECK_FIELD2}. Instead of putting the raw form data for a checkbox in the form, the checkboxes field ensures a Yes/No answer in the form. Errorpage: http://example.com/errorpage.html Works in conjunction with the Required header. If specified, redirects to the given URL if a required field is omitted. Error-query: on Passes the omitted field name as the query string to the page specified in Errorpage. Referer: example.com Referer: http://example.com/contact.html The referer can either be a domain to match or a full URL. If this header is included, the form will not send unless the referer matches the one in the template. Normally, Refererx should be used instead of this. Refererx: ^http://example.com/ Refererx is a more powerful version of the referer header. Instead of doing a simple match, Refererx does a regular expression match. This is the preferred way of doing referer matching. Refresh: http://example.com/refresh.html After the message has been successfully sent, refresh to http://www.example.com/refresh.html. Required: FIELD1,FIELD2,FIELD3 Comma-delimited list of fields that are required. If an error page is specified, FormBound will redirect to the error page. If not, FormBound will output a simple text message stating the missing field. TEMPLATE VARIABLES Template variables are specified as %{fieldname}, where the fieldname is the input name for a particular value. The only reserved name is id, which is always the name of the template as specified in the Formbound HTML data. There are, however, several special variable prefixes that can be used to make FormBound more powerful. If a variable name in a template begins with ENV_, the variable is assumed as an environment variable. If it begins with SVR_, it retrieves an Apache server variable. For example, to retrieve the IP address of the client, use %{SVR_REMOTE_ADDR}. To retrieve the PATH environment variable, use %{ENV_PATH}. Variables beginning with ESC_ are escaped with slashes. Variables beginning with CHECK_ are assumed to be checkboxes and their values in the e-mail will be Yes/No. The last special variable is %{flexmail}. It generates a formmail.cgi style e-mail with all of the variables submitted to the form. All of Formbound's other template features still work, but this is an easy way to generate a flexible form that captures all of the input variables. FORMBOUND SECURITY GUIDE Formbound is one of the most secure mail forms available today. The script employs several filters to prevent unauthorized use and spamming. However, Formbound's security can be compromised if the script is used improperly. This section details some of FormBound's security behaviors and proper security precautions. Any multiline input in a Formbound header will get truncated at the first newline. This circumvents a classic spam trick. Spammers send multiline inputs to header values in order to redirect the mail's output and change its content. Truncating multiline inputs prevents this from happening. Any time a variable is used as a name in a from field, it should be escaped. For example: From: "%{NAME}" <%{EMAIL}> should be changed to From: %{ESC_NAME}" <%{EMAIL}> This ensures that the name does not try to replace the e-mail address. TODO Some features I would like to implement in Formbound: Captcha authentication: A lot of scripts use this now, and Formbound needs to have this to be a full-featured secure mailer. GPG encryption: I had PGP encryption in the script at one point, but with PGP's declined use in *nix, a suitable GPG plugin would be nice. More advanced error field handling: Formbound's error handling is still crude in many ways. A better way of handling errors would make the script more powerful and help it integrate more seamlessly into forms.