Documentation for safemail.cgi

safemail.cgi is a web form that allows users to send feedback to BCN volunteers (or other BCN content providers). safemail.cgi forwards the comments via email.  It's created to solve two defects in other email form utilities:
Email CGI forms have benefits compared to mailto: URLs:

Quick Start for BCN Center and Business Pages

In order to hide email addresses from spambots, safemail uses nicknames. The nicknames for BCN center developers are the center name followed by the letters CD; for example, the nickname for the environment center developers is environmentCD.  In addition to the center developers, other key BCN developers are included in the list of BCN nicknames.  The list is included lower in this documentation.

Here's the HTML for a simple example:

   Send comments to
<a href="/cgi-bin/safemail.cgi?nickname=environmentCD">
the environment center developer.

The page editor may want to create a page (called thanks.html) that says "thanks for your comments".

  Send comments to
<a href="/cgi-bin/safemail.cgi?nickname=environmentCD&next_url=thanks.html">
the environment center developer.

The examples above are displayed as hyperlinks (underlined links). Alternatively, they can be specified as an HTML form; this will display a button.

  Send comments to the environment center developer.
<form method="POST" action="/cgi-bin/safemail.cgi">
<INPUT TYPE="hidden" NAME="nickname" Value="environmentCD">

The nickname parameter is mandatory; it accepts a list of nicknames separated by commas.  Additional  optional parameters are described below.

BCN Nickname List

The list of nicknames for BCN pages is in  /usr/local/etc/safemail/bcn.db.  As of 12/24/02, this list is:




























Quick Start for Hosted Sites

The procedure above works for BCN pages.  BCN also hosts many client sites.  These sites may also use safemail; but they will need to set up the comment page and list of nicknames.
  1. Create a template file - two approaches
  2. Verify that the template includes the elements described below
  3. Create a list of valid user nicknames and email addresses (described below)
  4. Mail the template and nickname list to me.

The Generated Email

The email sent to the nicknames will include
Here's a sample of the generated email.
Reply-to: (Joe User)
From: (Joe User)
To: BCN toolmaster
Subject: BCN Center Feedback
--- WARNING!!, the Reply-To email address --- --- is set by a site visitor and may not be legitimate. --- --- Check the Reply-To address carefully before replying. ---
Message From User:

This is a the most amazing email CGI form! The programmer must be brilliant.
The following information is derived from HTTP environmental variables (in parenthesis) that could be spoofed. Safemail was called from (HTTP_REFERER) The user's browser: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.0.2) Gecko /20021120 Netscape/7.01 (HTTP_USER_AGENT) The user's network address: (REMOTE_ADDR) The user's DNS host name: (REMOTE_HOST)
CGI variables:
(reply_to_name) Joe User
(tmpl_subject) BCN Center Feedback
(safemail_sendit) safemail_sendit
(debug) 1
(nickname) webmaster

Advanced Features

Logging and Error EMail

It's always annoying when I'm looking at a site, the web tools fail and give me debugging information. Rather than giving users cryptic error messages, safemail logs information to BCN file /usr/local/etc/safemail/ErrorLog.txt and sends mail to the nickname.

Smart follow-up pages

The default action in many CGI/email forms is to redisplay the send-email form after sending the mail; this is seldom what a user wants to see.  Safemail's default is to display a confirmation page for three seconds and then re-display the page that the user saw before the email form; a more likely candidate for the user to continue surfing.


The "look" of the form, the confirmation page, and an error page can be tailored to a site style.
I have included a BCN template with the standard look of most BCN pages.  This can be edited if the standard look changes without needed to change the CGI code itself.  A BCN client may opt for a different look in their comment forms; they can create their own template.  These templates must include:
Other optional hidden variables can be set as described below.

For example:

form method="POST" action="/cgi-bin/safemail.cgi">
<INPUT TYPE="hidden" NAME="nickname" Value="<Bogotag>nickname</Bogotag>">
Your Name:
<input type="text" name="reply_to_name">
Your E-Mail address: (optional)
<input type="text" name="reply_to">
<textarea name="comments" rows="10" cols="60">Enter comments here.</textarea>
<input type="submit" value="Submit Comments"> <input type="reset" value="Clear Comments">
<!-- <bogotag>hidden_vars</bogotag> -->

Nickname Database

The list of BCN nicknames is in /usr/local/etc/safemail/bcn.db and is summarized above.  The list has a nickname, a comma, and email address - one per line.  For example:

Details on Optional Parameters

next_url The URL of a page to display after the comments have been forwarded (for example, "thanks for the comments").   If the next_url hidden variable is not provided, then the referring page is the next_url (for example, if safemail is used on the environment center page and next_url is not set, then after the comments are submitted, the user will see the environmental center page.
next_url_delay The time in seconds after displaying the confirmation screen before redirecting to next_url or the page safemail was originally called from. 3 seconds
The name of a template file
bcn.tmpl (in /usr/local/etc/safemail/)
The names of the file containing the list of nicknames and email addresses
bcn.db (in /usr/local/etc/safemail/)
?? replace with email??
bcn.error.tmpl (in /usr/local/etc/safemail/)
subject (TBD)
The email subject header used in the web page.  This has precedence over tmpl_subject
tmpl_subject (if provided in the template) or "Website feedback form"
The email subject header.  Used just in a template file.
"Website feedback form"
The email address used in the Reply-to and From headers.
The name used in the Reply-to and From headers.

Normally this is set automatically.   This is set to "safemail_sendit" to indicate that the CGI script should send email.

The page that called safemail.cgi.  This variable can be overridden if called from a  form-submission front-end page.
the HTTP_REFERER of safemail.cgi
Set to anything causes safemail to write the email message to /tmp/safemailtest rather than actually sending the email.  Useful for testing.


TBD - one or more additional web-based tools to help users with safemail.

- list sites
- list users within a site
- if authorized, list users and email addresses
- request a new site
- remove a site
- validate a template

Questions? Comments? contact Paul von Behren