KaratEmail

A replacement for FormMail by MSU's Web and Digital Communciations Team

If you are the manager of a script that used to submit to FormMail and now uses KaratEmail please contact Web and Digital Communications to receive access to your form's submissions.

How to use KaratEmail:

  1. Create a form and set the form's action to "http://www.montana.edu/cgi-bin/karatemail/karatemail.pl"
    See the form demonstration below.
  2. Add special reserved fields to the form to add functionality.
  3. Create a form key from your KaratEmail dashboard to connect your new form to your user account.
  4. Publish your form to your website in order to start accepting submissions.
  5. Alternatively, you may contact Web and Digital Communications to connect your form with its submissions.

Log into KaratEmail:

Log into MSU's KaratEmail serivce to retrieve your form submissions. You will need your NetID to authenticate to the service.

 

Background Information

After over a decade of using the renowned FormMail script that was developed by Matt's Script Archive, the university found the need to better handle form submissions to both build on the functionality of FormMail and develop the vulnerability protections that FormMail lacked due to the projects stagnation. To fill these needs, the Web and Digital Communications team built from scratch a new form submissions handler called KaratEmail that could be take the place of FormMail without any editing of individual forms using FormMail.

All forms that were submitting data to MSU's FormMail script will continue to function without modification on the part of the form's owner. The KaratEmail script will not email individual form submissions, but rather you will receive a notification once a day that you have new form submissions to review.

At some point in the future, we will be releasing the KaratEmail script as open source. Given the common use of FormMail across the Web, we expect that our development could be of use to other developer's and system administrators across the Web.

 

Reserved Fields

recipientThis field is required by KaratEmail.
This should be the owner of the form.
Example – This form would be owned by websupport@montana.edu.

<input type="hidden" name="recipient" value="websupport@montana.edu" />


subject
This field is required by KaratEmail.
This should be the title of the form.
Example – This form is titled 'Hello World!'

<input type="hidden" name="subject" value="Hello World!" />


redirect

This is the URL that the form will redirect the visitor to after the form's submission has been processed. It must be listed in the safe domain's list.
Example – The form will redirect to http://www.montana.edu after its submission is processed.

<input type="hidden" name="redirect" value="http://www.montana.edu" />


required

This should list the fields that are required to submit the form. Field names should be separated with a comma.
Example – The form will require the first_name and last_name fields have values.

<input type="hidden" name="required" value="first_name,last_name" />


missing_fields_redirect

This should list the url that the form is redirected to if one or more required fields are not present. It must be listed in the safe domain's list.
Example – The form will redirect to http://www.montana.edu/missing/ if it is missing a required field.

<input type="hidden" name="missing_fields_redirect" value="http://www.montana.edu/missing/" />


All other fields

These will be captured and stored in an object to be retrieved by the form's owner at some future point.

Example – text input field

Full name: <input type="text" name="text_example" value="" />

See Demonstration

Example – radio button input field

<input type="radio" name="radio_example" value="Yes" />  Yes 
<input type="radio" name="radio_example" value="No" />  No

See Demonstration

Example – checkbox input field

<input type="checkbox" name="terms" value="I agree" /> I understand and agree to the terms.

See Demonstration

Example – checkbox array of input fields

<input type="checkbox" name="checkbox_group[]" value="Red" /> Red
<input type="checkbox" name="checkbox_group[]" value="Green" /> Green
<input type="checkbox" name="checkbox_group[]" value="Blue" /> Blue

See Demonstration

Example – select field

<select name="select_example">
  <option value="Option 1">Option 1</option>
  <option value="Option 2">Option 2</option>
  <option value="Option 3">Option 3</option>
  <option value="Option 4">Option 4</option>
  <option value="Option 5">Option 5</option>
</select>

See Demonstration

Example – multi-select field (Please note the "[]" appended to the name.)

<select name="multi_select_example[]" multiple>
  <option value="Option 1">Option 1</option>
  <option value="Option 2" selected="selected">Option 2</option>
  <option value="Option 3">Option 3</option>
  <option value="Option 4">Option 4</option>
  <option value="Option 5" selected="selected">Option 5</option>
</select>

See Demonstration

Example - textarea field

<textarea name="missing_fields_redirect" cols="40" rows="4"></textarea>
See Demonstration
 

Honeypot Form Protection

Honeypot is generally an effective first line of defense against spam. The fields that are added to your form are invisible to the user and should remain empty. However, the honeypot fields appear to be valid fields to most spam scripts and are given values upon submission. When the form is submitted KaratEmail checks to see if the honeypot fields have caught a spam submission.

Step 1: Add the following code inside your Web page's <head>:

<style type="text/css">
.hpreqSetting { display:none;visibility:hidden; }
</style>

Step 2: Add the following code inside your <form>:

<div class="hpreqSetting">
 <input type="text" name="hpreq_name" autocomplete="off">
 <input type="text" name="hpreq_email" autocomplete="off">
</div>

Form Key

Including an <input> named "form_key" in any newly-created <form> allows KaratEmail to instantly connect your user account with the new form, granting you access to all future form submissions in one step. 

Step 1: Log in to the KaratEmail dashboard and select "Create Form Key" from the main navigation menu.  Follow the directions on the page to generate your new form key, then copy the form key to the clipboard.

Step 2: Add the following code inside your <form>:

<input type="hidden" name="form_key" value="insert form_key you generated within KaratEmail here" />


Step 3:
Perform a test submission of your new form.  You will see the form and new submission appear in your KaratEmail dashboard.  If you wish, you may grant other users access to the form submissions as well.

 

Demonstration Form

Example Source Code | Example Output

    * required

          

               



 

Demonstration Source

Example Form | Example Output

<form id="demoform" action="http://www.montana.edu/cgi-bin/karatemail/karatemail.pl">
<input type="hidden" name="recipient" value="websupport@montana.edu" />
<input type="hidden" name="subject" value="KaratEmail Demo" />
<input type="hidden" name="redirect" 
                     value="/web/services/karatemail/?demo=success#demo" /> <strong class="red">* required</strong>
<input type="hidden" name="required" value="name" />
<input type="hidden" name="missing_fields_redirect" 
                     value="/web/services/karatemail/?demo=missing#demo" />
<div class="hpreqSetting">
 <input type="text" name="hpreq_name" autocomplete="off">
 <input type="text" name="hpreq_email" autocomplete="off">
</div>

<fieldset>
 <p><label for="name">What is your name?</label>    
 <input type="text" name="name" id="name" value="" /></p>
 <p><label>What is your quest?</label>    
 <input type="radio" name="quest" id="grail-pass" value="To find the Holy Grail" /> 
 <label for="grail-pass">To find the holy grail.</label>       
 <input type="radio" name="quest" id="nonanswer-fail" value="I don't know." /> <label for="nonanswer-fail">I don't know.</label></p>
 <p><input type="checkbox" name="bird_knowledge" id="bird_knowledge" value="Yes. I know all about Swallows." /> 
 <label for='bird_knowledge'>Yes. I know all about the carrying capacity of laden Swallows.</label></p>
 
 
 <p><label>What is your favorite color?</label> 
 <input type="checkbox" name="favorite_color[]" id="color_red" value="Red" /> 
 <label for="color_red">Red</label>    
 <input type="checkbox" name="favorite_color[]" id="color_blue" value="Blue" /> 
 <label for="color_blue">Blue</label>    
 <input type="checkbox" name="favorite_color[]" id="color_green" value="Green" /> 
 <label for="color_green">Green</label>    
 <input type="checkbox" name="favorite_color[]" id="color_gold" value="Gold" /> 
 <label for="color_gold">Gold</label>   </p>
 
 
 <p><label for="windspeed">What is the average wind-speed velocity of a laden swallow?</label> 
<select name="windspeed" id="windspeed">
  <option value="">--</option>
  <option value="10 km/h">10 km/h</option>
  <option value="20 km/h">20 km/h</option>
  <option value="25 km/h">25 km/h</option>
  <option value="African or European?">African or European?</option>
</select></p>

 <p><label for="camelot_is">Camelot is ...?</label><br>
<select name="camelot_is[]" id="camelot_is" multiple>
  <option value="a piece of English history">a piece of English history</option>
  <option value="a piece of Authorian legend">a piece of Authorian legend</option>
  <option value="a silly place" selected>a silly place</option>
  <option value="the home to King Author's Court">the home to King Author's Court</option>
  <option value="a hotel in Las Vegas">a hotel in Las Vegas</option>
  <option value="only a model" selected>only a model</option>
</select></p>

<p><label for="something_completely_different">And now for something completely different.</label><br>
<textarea name="something_completely_different" id="something_completely_different" cols="40" rows="4"></textarea>
</p>
 
 
 <input type="submit" style="font-size:14px;padding:5px;" value="Submit Form »" />
</fieldset> 
</form>
 

Demonstration Output

Example Form | Example Source Code

Demonstration output of the form submission