Formmail

From DreamHost
Jump to: navigation, search

Overview

DreamHost offers a simple and free contact form option called ‘Formmail’ which you can use to build a very simple contact form on your website.

Here is an example form:

01 Formmail.fw.png

Users can use this page on your website to reach you, and the form can also be customized if you have knowledge in HTML scripting.

Creating a form

You can add the Formmail code to any .html file you like, but it helps to have a basic knowledge of HTML coding to create this file. Please note the following restrictions:

  • The recipient email address must be a DreamHost email address. Gmail, Hotmail, AOL (and so on) emails cannot be used. However, you can set up a forward email on a separate DreamHost domain.
  • The domain on which Formmail is set up must be hosted on a DreamHost server.
  • No file uploads are available.
  • Foreign languages such as Chinese are not available.

To start off, you will need the script that your form ues to make all of this work. The action of your form must point to the script shown below, and the method must be POST or GET in capital letters. Therefore, you must use this exact HTML in your form:

<form action="http://formmail.dreamhost.com/cgi-bin/formmail.cgi" method="POST">

Example

Here is a very simple Formmail example to give you an idea of how you piece this together, and you can modify it to your specific needs.

This following code can be added to a simple .html or .php file:

<form action="http://formmail.dreamhost.com/cgi-bin/formmail.cgi" method="POST">
<input type="hidden" name="recipient" value="email address">
<input type="hidden" name="subject" value="Your Subject line goes here">
Full Name: <input type="text" name="name" size="60" style="width: 300px"><br />
Email: <input type="text" name="email" size="60" style="width: 300px"><br />
phone: <input type="text" name="name" size="60" style="width: 300px"><br />
Comments: <textarea name="Comments" rows="8" wrap="wrap" style="width: 300px"></textarea><br />
<input type="submit" value="Send">
</form>
Important icon.png Important: Use "name" instead of "id" to reference form objects.


Protecting the recipient email

The original example has several problems. Most significantly, the recipient's email address is exposed and will be assaulted by spam. There is also no way to prevent someone from attacking the form by setting up a "bot" to repeatedly send email. Someone can also modify the form and abuse it as a sort of open mail relay to send anonymous email.

DreamHost does allow sites to make server-to-server connections while processing a user's request. To hide the recipient email, you can set up a form that receives the HTTP POST containing all of the form elements shown above, except for the recipient field. The form can post to a PHP script.

On receiving the post data:

  1. verify that it matches any data you want
  2. verify the Captcha
  3. insert the recipient field into the POSTDATA
  4. open a server side connection to http://formmail.dreamhost.com/cgi-bin/formmail.cgi

Of course, people can still find ways to abuse the DreamHost formmail script by attacking it directly, but this does add an extra layer of defense.

Here is an implementation sketch using Python. What you actually need to do depends on your web framework, and you might also be able to have another language's framework invoke this as a script:

#!/usr/bin/env python

import urllib
import urllib2

def send_mail(postdata):
   '''This function is called after receiving an HTTP POST. postdata is a dict() containing the form keys and values.'''

   # What you have to do here depends on your framework, but you probably want to filter unexpected fields
   ensure_postdata_is_safe(postdata)

   postdata['recipient'] = 'YOUR@EMAIL.ADDRESS.COM'
       
   # urlencode it to the expected format
   urlenc = urllib.urlencode(postdata)
      
   try:
       # Have the server open a connection to formmail and send it on the client's behalf
       response = urllib2.urlopen('http://formmail.dreamhost.com/cgi-bin/formmail.cgi', urlenc, timeout=250)
       # If the server to server connection succeeds, let the client know
       if response.code != 200: # 200 is HTTP OK
           return redirect('failed to send message')
   except urllib2.URLError, e:
       abort(500)  # That is, send an HTTP 500 to the client
       
   return redirect('success page')

Field descriptions and examples

Below is a table that lists the form fields that you can use to customize your forms and the code needed to implement them. Any other form fields that appear in your script will be mailed back to you. If you do not have the redirect field set, they will also be displayed on the resulting page. There is no limit to how many other form fields you can use with this form.

Field Description Syntax

recipient

  • RECIPIENT IS THE ONLY REQUIRED FORM FIELD.
  • Allows you to specify to whom you wish for your form results to be mailed to. Most likely, you'll want to configure this option as a hidden form field with a value equal to that of your email address.
  • New: You can also set your email address to use a "#" instead of an "@" in this field, in an attempt to foil spam-spiders from crawling your web page. For example, if your email recipient is john@doe.com, you can set the value of the recipient field to be john#doe.com and it'll work.
  • Even better, you can also just leave off the @example.com part and the script automatically appends the domain your form is posted on.
<input type="hidden" name="recipient" value="email@your.host.com">

subject

  • Allows you to specify the subject that you wish to appear in the email that is sent to you after this form has been filled out.
  • If you do not have this option turned on, then the script defaults to a message subject: WWW Form Submission.
  • If you wish to choose a subject:
<input type="hidden" name="subject" value="Your Subject">
  • To allow the user to choose a subject:
<input type="text" name="subject">

email

  • Allows the user to specify their return email address.
  • If you want to be able to return email to your user, you must include this form field and allow them to fill it in. This will be put into the ’From:’ field of the message you receive.
  • If you want to require an email address with valid syntax, add this field name to the 'required' field.
  • View the ‘required’ field below for further details.
<input type="text" name="email">

realname

  • Allows the user to input their realname.
  • This field is useful for identification purposes and will also be put into the ’From:’ line of your message header.
<input type="text" name="realname">

redirect

  • Redirects the user to a different URL.
  • Instead of having them see the default response to the fill-out form, you can use this hidden variable to send them to a pre-made HTML page.
  • To choose the URL they will end up at:
<input type="hidden" name="redirect" value="http://your.host.com/to/file.html">
  • To allow them to specify a URL they wish to travel to once the form is filled out:
<input type="text" name="redirect">

required

  • Sets up certain fields to require information to be filled in before the user can successfully submit the form.
  • Simply place all field names that you wish to be mandatory into this field.
  • If the required fields are not filled in, the user is notified of what they need to fill in, and a link back to the form they just submitted is provided.
  • If you want to require that users fill in the email address and phone number fields in your form so that you can reach them once you have received the mail:
<input type="hidden" name="required" value="email,phone">

env_report

  • Allows you to have Environment variables included in the email message you receive after a user has filled out your form.
  • This is useful if you wish to know which browser was used, what domain they came from, or any other attributes associated with the environment variables.
  • The following is a list of all valid environment variables you can use with formmail:
REMOTE_ADDR – Sends the IP address of the remote host making the request.
REMOTE_USER – If server supports authentication and the script is protected, then this is the username they have authenticated as (this is not usually set).
HTTP_USER_AGENT – The browser the client is using to send the request.
HTTP_REFERER – The URL they submitted this form from (note the ONE "r").
  • If you want to find the IP address and browser sending the request:
<input type="hidden" name="env_report" value="REMOTE_ADDR,HTTP_USER_AGENT">

sort

  • Allows you to choose the order in which you wish for your variables to appear in the email that Formmail generates.
  • You can choose to have the field sorted alphabetically or specify a set order in which you want the fields to appear in your mail message.
  • By leaving this field out, the order simply defaults to the order in which the browsers sends the information to the script (which is usually the exact same order as they appeared in the form.)
  • When sorting by a set order of fields, you should include the phrase "order:" as the first part of your value for the sort field, and then follow that with the field names you wish to be listed in the email message, separated by commas (spaces and new lines are okay).
  • To sort alphabetically:
<input type="hidden" name="sort" value="alphabetic">
  • To sort by a set field order:
<input type="hidden" name="sort" value="order:name1, name2, etc...">

print_config

  • Allows you to specify which of the config variables you would like to have printed in your email message.
  • By default, no config fields are printed to your email. This is because the important form fields, such as email, subject, and so on are included in the header of the message. However, some users have asked for this option so they can have these fields printed in the body of the message.
  • The config fields that you wish to have printed should be in the value attribute of your input tag separated by commas.
  • If you want to print the email and subject fields in the body of your message:
<input type="hidden" name="print_config" value="email,subject">

print_blank_fields

  • Allows you to request that all form fields are printed in the return HTML, regardless of whether or not they were filled in.
  • Formmail defaults print_blank_fields to 'off', so that unused form fields aren't emailed.
  • If you want to print all blank fields:
<input type="hidden" name="print_blank_fields" value="1">

date_offset

  • Overrides the local server time (Pacific Standard Time) in the emails you get from Formmail.
  • Use an offset from GMT in hours, like "4" or "-5".
  • If you want to use Eastern Standard Time:
<input type="hidden" name="date_offset" value="-5">

title

  • Allows you to specify the title and header that appear on the resulting page if you do not specify a redirect URL.
  • If you want a title of 'Feedback Form Results':
<input type="hidden" name="title" value="Feedback Form Results">

return_link_url

  • Allows you to specify a URL that will appear as return_link_title on the following report page.
  • The return_link_url field won't be used if you have the redirect field set, but it is useful if you allow the user to receive the report on the following page and want to offer them a way to get back to your main page.
  • You must include return_link_title to go along with this.
<input type="hidden" name="return_link_url" value="http://your.host.com/main.html">

return_link_title

  • Links the title back to the page you specify with return_link_url.
  • You must have return_link_url specified.
  • The two fields are shown on the resulting form page as:
<a href="http://your.host.com/main.html">Back to my site.</a>
<input type="hidden" name="return_link_title" value="Back to my site.">

missing_fields_redirect

  • Allows you to specify a URL that users are redirected to if there are fields listed in the required form field that are not filled in.
  • You can customize an error page instead of displaying the default.
<input type="hidden" name="missing_fields_redirect" value="http://your.host.com/error.html">

background

  • Allows you to specify a background image that appears if you do not have the redirect field set.
  • This image appears as the background to the form results page.
<input type="hidden" name="background" value="http://your.host.xxx/image.gif">

bgcolor

  • Allows you to specify a background color appears.
  • This color appears as the background to the form results page.
<input type="hidden" name="bgcolor" value="#FFFFFF">

text_color

  • Works in the same way as bgcolor, except that it will change the color of the text.
  • For a text color of Black:
<input type="hidden" name="text_color" value="#000000">

link_color

  • Changes the color of links on the resulting page if you do not have the redirect field set.
  • Works in the same way as text_color.
  • For a link color of Red:
<input type="hidden" name="link_color" value="#FF0000">

vlink_color

  • Changes the color of visited links on the resulting page if you do not have the redirect field set.
  • Works exactly the same as link_color.
  • For a visited link color of Blue:
<input type="hidden" name="vlink_color" value="#0000FF">

alink_color

  • Changes the color of visited links on the resulting page if you do not have the redirect field set.
  • Works exactly the same as link_color.
  • For an active link color of Blue:
<input type="hidden" name="alink_color" value="#0000FF">

See also