Personal Web Space

Using Mail-to Forms on an Unix VWS

This document assumes that you know and understand html code and forms, and how they work together. If not, there are lots of pointers to that information in the technical documentation section of the Magma Webserver.

Which server is your VWS on?

Express 1 or 2
Express 3

Express1 / Express2 VWS:

This documentation is for customers who have a Magma "Express 1 or 2" VWS. Because "Express 1 or 2" VWS customers do not have their own CGI-BIN (script) directory, you will be using the mailto CGI which is located in the shared CGI-BIN directory on the server which hosts your website.

The mail-to script

To use the mail-to script, your form must contain the following fields:

  • to
  • body
  • from

To access the mailto script, just call the mailto script in your form command:

<FORM METHOD="POST" ACTION="http://express1or2x.magma.ca/cgi-bin/mailto">
the form action - replace "express1or2x" with the hostname of the server on which your site is hosted. (e.g. http://express2b.magma.ca/cgi-bin/mailto).

<INPUT TYPE="hidden" name="body" value="nothing">
a required field
<INPUT TYPE="hidden" name="to" value="user@magmacom.com">
where to send the message
<INPUT NAME="from" SIZE=20>
ask the user for their email address
<INPUT type="submit" value="submit">
the submit button
end the form

Additional variables:

Subject: <INPUT TYPE="hidden" name="sub" value="Email Subject">
The 'sub' (subject) value will be used as the subject of the message when it is sent.

Next URL: <INPUT TYPE="hidden" name="nexturl" value="http://www.magmacom.com/~userid/thankyou.html">
thankyou.html must be created by the customer and can be replaced by any page you prefer your visitors to see after they submit to your form. The 'nexturl' value will be the page displayed after the person hit's SUBMIT on your form. You would generally put some sort of 'thank you' on this page.

When a user selects the Submit button, email is sent that looks like the following:

Date: Mon, 15 May 1995 11:40:41 -0400
From: user@somewhere.com
To: submissions@company.com
Subject: Form submission


BBS -> Springfield BBS
NAME -> Bob Smith
LINES -> 4
AREA -> 123
PHNUMBER -> 555-1234
BPS -> 28800
OPEN -> 0-24
COST -> Donation or fee optional
MAIL -> on
GAMES -> on
Submit to list maintainer -> Submit Query

Complete HTML form sample:
you must replace userid@magma.ca with your magma email.

<form method="post" action="/cgi-bin/mailto">
<INPUT TYPE="hidden" name="nexturl" value="http://www.magma.ca">
<input type="hidden" value="userid@magma.ca" size=40 name="to">

<table width=50% border=0>
<td> From : </td>
<td> <input value="userid@isp.com" size=40 name="from"></td>
<td> Subject : </td>
<td> <input value="" size=40 name="sub"></td>
<td> How did you hear about my website : </td>
<td> <select name="how did you hear about my website" size="1">
<option> reason 1
<option> reason 2
<option> reason 3
<option> reason 4

<td> Comments : </td>
<textarea name="body" rows=6 cols=40 value=""></textarea>

<td colspan=2><input type="submit" value="submit">
<input type="reset" value="reset"></td>

Back to top

Express3 VWS:
With an Express3 vws you have a copy of the formmail.pl file located in your cgi-bin folder, you will have to edit this file manually to change how it works.


To make use of it, you need to write an HTML form that refers to the FormMail script. Here's an example which will send mail to the address 'feedback@your.domain' when someone submits the form:

<form method="post" action="http://your.domain/cgi-bin/FormMail.pl">
<input type="hidden" name="recipient" value="feedback@your.domain">
<input type="text" name="feedback"><br>
Please enter your comments<br> <input type="submit"> </form>

See how the hidden 'recipient' input in the example above told formmail who to send the mail to ? This is how almost all of formmail's configuration works. Here's the full list of things you can set with hidden form inputs:

recipient - The email address to which the form submission should be sent. If you would like it copied to more than one recipient then you can separate multiple email addresses with commas, for example:
  <input type="hidden" name="recipient" value="you@your.domain,me@your.domain">
  If you leave the 'recipient' field out of the form, formmail will send to the first address listed in the @allow_mail_to configuration variable (see above). This allows you to avoid putting your email address in the form, which might be desirable if you're concerned about address harvesters collecting it and sending you SPAM. This feature is disabled if the $emulate_matts_code configuration variable is set to 1.
subject The subject line for the email. For example: <input type="hidden" name="subject" value="From the feedback form">
redirect If this value is present it should be a URL, and the user will be redirected there after a successful form submission. For example:

<input type="hidden" name="redirect" value="http://www.your.domain/foo.html">

If you don't specify a redirect URL then instead of redirecting formmail will generate a success page telling the user that their submission was successful.
bgcolor The background color for the success page.
background The URL of the background image for the success page.
text_color The text color for the success page.
link_color The link color for the success page.
vlink_color The vlink color for the success page.
alink_color The alink color for the success page.
title The title for the success page.
return_link_url The target URL for a link at the end of the success page. This is normally used to provide a link from the success page back to your main page or back to the page with the form on. For example:

<input type="hidden" name="return_link_url" value="/home.html">
return_link_title The label for the return link. For example:

<input type="hidden" name="return_link_title" value="Back to my home page">
sort This sets the order in which the submitted form inputs will appear in the email and on the success page. It can be the string 'alphabetic' for alphabetic order, or the string "order:" followed by a comma separated list of the input names, for example:

<input type="hidden" name="sort" value="order:name,email,age,comments">

If "order:" is used you must supply the names of all of the fields that you want to be in the body of the mail message.
print_config This is mainly used for debugging, and if set it causes formmail to include a dump of the specified configuration settings in the email. For example:

<input type="hidden" name="print_config" value="title,sort">

... will include whatever values you set for 'title' and 'sort' (if any) in the email.
required This is a list of fields that the user must fill in before they submit the form. If they leave any of these fields blank then they will be sent back to the form to try again. For example:

<input type="hidden" name="required" value="name,comments">
missing_fields_redirect If this is set, it must be a URL, and the user will be redirected there if any of the fields listed in 'required' are left blank. Use this if you want finer control over the the error that the user see's if they miss out a field.
env_report This is a list of the CGI environment variables that should be included in the email. This is useful for recording things like the IP address of the user in the email. Any environment variables that you want to use in 'env_report' in any of your forms will need to be in the @valid_ENV configuration variable described above.
print_blank_fields If this is set then fields that the user left blank will be included in the email. Normally, blank fields are suppressed to save space.

As well as all these hidden inputs, there are a couple of non-hidden inputs which get special treatment:

email If one of the things you're asking the user to fill in is their email address and you call that input 'email', formmail will use it as the address part of the sender's email address in the email.
realname If one of the things you're asking the user to fill in is their full name and you call that input 'realname', formmail will use it as the name part of the sender's email address in the email.

Back to top