Working with ExpressionEngine’s stock email form

Recent addons for building forms in ExpressionEngine® from Solspace, Metasushi, and DevDemon provide ways of creating and editing forms via the control panel. However, if you only need a simple form, the addon price is out of budget, or the free offering from Solspace is too time consuming to use, then ExpressionEngine’s stock email form is always available for you to use.

EE’s email form module can be used to build up some quite complex forms but can often confuse new developers, so here’s a rundown of a few techniques you can use. Note there are no backend settings for the form module, just template tags.

I’ll start by building a basic form then adding various methods to build up a comprehensive form.

Standard fields

subject (required) - in the received email this is the email’s Subject/Title
name (optional) - in the received email this is the email’s “From” name
email (required) - in the received email this is the reply to address
to (optional) - send the email to a custom address (use with care!)
message (optional) - the email’s textual message
captcha (optional) - only used when you use EE’s inbuilt CAPTCHA field

A basic form

This form will allow the user to input their own “Subject” text, and submit their name, email address and a message.

{exp:email:contact_form recipients=“admin@example.com” charset=“utf-8”}

<label for=“subject”>Subject</label>
<input type=“text” id=“subject” name=“subject” value=“Contact form” />

<label for=“name”>Name</label>
<input type=“text” id=“name” name=“name” value=”{member_name}” />

<label for=“from”>Email address</label>
<input type=“email” id=“from” name=“from” value=”{member_email}” />

<label for=“message”>Message</label>
<textarea id=“message” name=“message”></textarea>

{if captcha}
Please enter the word you see in the image below:<br/>
{captcha} <input type=“text” name=“captcha” maxlength=“20” />
{/if}

<input type=“submit” value=“Submit” />

{/exp:email:contact_form}

Using a pre-defined “subject”

If you want to hard code the subject simply change the INPUT type to “hidden”, and remove the LABEL field as you’ll no longer need it:

<input type=“hidden” name=“subject” value=“My custom subject” />

If you want to use the Title from the current Channel entry you can wrap the form inside a Channel entries tag, then populate the INPUT with the entry’s title variable - useful for things like specific “product” or “services” enquiries!

{exp:channel:entries channel=“services” limit=“1”}
{exp:email:contact_form recipients=“admin@example.com” charset=“utf-8”}

<input type=“hidden” name=“subject” value=”{title} enquiry” />

...other form fields...

{/exp:email:contact_form}
{/exp:channel:entries}

Adding extra fields

Once you go beyond a single “message” field you need to change the syntax slightly by using “message[]” as the INPUT name for all extra fields (other than subject, name, email, to and captcha!):

Text input

<label for=“age”>Your age</label>
<input type=“text” id=“age” name=“message[]” />

Textarea

<label for=“message”>Message</label>
<textarea id=“message” name=“message[]”></textarea>

Select

<label for=“colour”>Favourite colour</label>
<select id=“colour” name=“message[]”>
<option value=“Red”>Red</option>
<option value=“Green”>Green</option>
<option value=“Blue”>Blue</option>
</select>

Radio

<p>Do you like cheese?</p>
<label for=“yes”><input type=“radio” id=“yes” name=“message[]” value=“Yes” /> Yes</label>
<label for=“no”><input type=“radio” id=“no” name=“message[]” value=“No” /> No</label>

Checkbox

<p>What cheeses do you like?</p>
<label for=“edam”><input type=“checkbox” id=“edam” name=“message[]” value=“Edam” /> Edam cheese</label>
<label for=“cheddar”><input type=“checkbox” id=“cheddar” name=“message[]” value=“Cheddar” /> Cheddar cheese</label>
<label for=“stinky”><input type=“checkbox” id=“stinky” name=“message[]” value=“Stinky” /> Stinky cheese</label>

Prettifying the email

By default EE will just send data from your message and other extra fields in a big lump, so making the email copy easily readable makes sense. You can add in some hidden fields that act as sub headings in the email body, again using the “message[]” name for the hidden field.

<label for=“age”>Your age</label>
<input type=“hidden” name=“message[]” value=”—Age—” />
<input type=“text” id=“age” name=“message[]” />

<label for=“colour”>Favourite colour</label>
<input type=“hidden” name=“message[]” value=”—Favourite colour—” />
<select id=“colour” name=“message[]”>
<option value=“Red”>Red</option>
<option value=“Green”>Green</option>
<option value=“Blue”>Blue</option>
</select>

<label for=“message”>Message</label>
<input type=“hidden” name=“message[]” value=”—Message—” />
<textarea id=“message” name=“message[]”></textarea>

In the received email this might look something like this:

—Age—
42

—Favourite colour—
Blue

—Message—
Hello!

Including “hidden” form data

Sometimes you may want to include extra data in your form over and above what the user inputs, for instance the date/time the form was sent, channel entry data, or member data.

Here’s an example that adds the logged in user’s member group name, or if they are logged out supply a “Not logged in” message.

<!— member group name —>
<input type=“hidden” name=“message[]” value=”—Member group—” />
{if logged_in}
<input type=“hidden” name=“message[]” value=”{group_title}” />
{/if}
{if logged_out}
<input type=“hidden” name=“message[]” value=“Not logged in” />
{/if}

Specifying different recipents

Sometimes you need to send the email to different people, such as when selecting a specific type of enquiry.

First you need to add the parameter user_recipients=“yes” to your form tag:

{exp:email:contact_form user_recipients=“yes” recipients=“admin@example.com” charset=“utf-8”}

Then add a SELECT input with your options:

<label for=“dept”>Department</label>
<select id=“dept” name=“to”>
<option value=“sales@example.com”>Sales</option>
<option value=“support@example.com”>Support</option>
<option value=“billing@example.com”>Billing</option>
</select>

Note: it’s highly recommended to use a SELECT input here to prevent abuse by spammers, also use a CAPTCHA or other form protection for added security!

Complete form example using all input types

{exp:email:contact_form recipients=“admin@example.com” charset=“utf-8”}

<!— subject —>
<input type=“hidden” name=“subject” value=“My custom subject” />

<!— name —>
<label for=“name”>Name</label>
<input type=“text” id=“name” name=“name” value=”{member_name}” />

<!— email address —>
<label for=“from”>Email address</label>
<input type=“email” id=“from” name=“from” value=”{member_email}” />

<!— member group name —>
<input type=“hidden” name=“message[]” value=”—Member group—” />
{if logged_in}
<input type=“hidden” name=“message[]” value=”{group_title}” />
{/if}
{if logged_out}
<input type=“hidden” name=“message[]” value=“Not logged in” />
{/if}

<!— text input example —>
<label for=“age”>Your age</label>
<input type=“hidden” name=“message[]” value=”—Age—” />
<input type=“text” id=“age” name=“message[]” />

<!— select example —>
<label for=“colour”>Favourite colour</label>
<input type=“hidden” name=“message[]” value=”—Favourite colour—” />
<select id=“colour” name=“message[]”>
<option value=“Red”>Red</option>
<option value=“Green”>Green</option>
<option value=“Blue”>Blue</option>
</select>

<!— radio button example —>
<p>Do you like cheese?</p>
<input type=“hidden” name=“message[]” value=”—Likes cheese?—” />
<label for=“yes”><input type=“radio” id=“yes” name=“message[]” value=“Yes” /> Yes</label>
<label for=“no”><input type=“radio” id=“no” name=“message[]” value=“No” /> No</label>

<!— checkboxes example —>
<p>What cheeses do you like?</p>
<input type=“hidden” name=“message[]” value=”—Cheeses liked—” />
<label for=“edam”><input type=“checkbox” id=“edam” name=“message[]” value=“Edam” /> Edam cheese</label>
<label for=“cheddar”><input type=“checkbox” id=“cheddar” name=“message[]” value=“Cheddar” /> Cheddar cheese</label>
<label for=“stinky”><input type=“checkbox” id=“stinky” name=“message[]” value=“Stinky” /> Stinky cheese</label>

<!— textarea example —>
<label for=“message”>Message</label>
<input type=“hidden” name=“message[]” value=”—Message—” />
<textarea id=“message” name=“message[]”></textarea>

<!— captcha example —>
{if captcha}
Please enter the word you see in the image below:<br/>
{captcha} <input type=“text” name=“captcha” maxlength=“20” />
{/if}

<input type=“submit” value=“Submit” />

{/exp:email:contact_form}

The output for the complete form may look something like:

From: Rob
Subject: My custom subject

—Member group—
Silver members