The WWW Mail Gateway Info
This little package is a totally self-contained perl script, which
can be had right here. If you
want to have a mail gateway in your HTML, but can't run the script for
yourself, just make a link that points here, and give it standard GET
method variables. An example of this is at the bottom of
my home page. If you can't run your own copy of
the script, you can use ours. What
makes The WWW Mail Gateway better than mailto: URLs is the fact that
you can give it default values for nearly every field.
Here are the variables you can pass using the GET method that
have special meaning to the gateway. When you use the GET method,
you get the default mail form from the script.
- to
- Specifies the default mail address of the user to send mail to. If
restricted mail addresses are enabled, then this field specifies
the address that shows up default in the selection list.
- cc
- Specifies the carbon copy mail address. Does not work when
restricted mail addresses are enabled.
- from
- This value normally comes from the CGI variables REMOTE_IDENT and
REMOTE_HOST to form a guess at the mail address, or if the remote
user is running Netscape, then REMOTE_USER is used instead. If
from is passed manually, then these methods are overridden.
- sub
- Gives the default subject for the mail. No strings attached here.
- body
- Specifies the default body text. This is very useful for feedback
forms or surveys. You can't include too much here because of
the GET method limit on the number of characters passed. I don't
happen to know what this is off the top of my head.
- nexturl
- This tells the browser what URL to retrieve after mail is sent.
If this is undefined, the user gets a short "mail sent"
confirmation message. If you want to be friendly, you should
define this.
All other cgi variables, whether hidden or part of a fill-out form
will be logged after the body portion. This means questionairres
via mail can be easily implemented.
These variables can be supplied in the GET request when linking
to the mailto script. If you simply want your mail address to
be given in the mail form, make your HTML look something like this:
<A HREF="/cgi-bin/mailto.pl?to=your@mail.address">
The URL in the HREF tag should be changed to the full URL of the script.
If you're using the one on this site, use
http://www-bprc.mps.ohio-state.edu/cgi-bin/mailto.pl.
If you want your default subject to be "Wow! Spiffy!" then give the
sub variable separated by an ampersand (each variable/value pair
should be separated by one ampersand):
<A HREF="/cgi-bin/mailto.pl?to=your@mail.address&sub=Wow!++Spiffy!">
Notice that all spaces were replaced with plus signs -- spaces are not
allowed in URLs. Also note that plusses must then be specified in hex
with %2B. Other HTML-reserved characters must also be specified in
the same way.
One special use of CGI variables here would be to include multiple
questions to form a kind of questionare to be filled out via email.
It's sometimes convenient to not cram all the body text into one big
chunk of text, or maybe different fields are necessary if you're
making your own FORM interface to the gateway. In this case, you can
specify parts of the body text in different 'body' variables using GET
or POST. When more than one 'body' variable is encountered, they are
effectively concatenated to form one large body text.
New in version 2.0, you don't have to rely on the body
concatentaion feature to get your fill-out forms done easily. Every
CGI variable in your mail form that does not have a special meaning to
the WWW Mail Gateway will be logged at the bottom of the mail in
variable/value pairs that look like this:
variable -> value
You could also compose a mail form that contains only a fill out form
to be logged, but one of the CGI variables must be named "body" to
fool the gateway into thinking it has been filled out properly.
Creative users will take this opportunity to use the "body" variable
as a hidden variable in their forms to make the output a little more
readable or include useful information. Always be sure to include the
to and from variables correctly filled out in some form
or another as well. Also be sure to point the ACTION tag of your form
to the right script URL using the POST method.
If you wish to run your own copy of The WWW Mail Gateway (very
preferable), you must be running a UNIX type system with sendmail
properly configured and installed. First download the perl source code.
There should be relatively few changes to be made in the beginning of
the source:
- Most importantly, $sendmail needs to be defined as the full pathname
of your sendmail executable, with necessary flags. This can
be configured (in a less secure way) to set the actual from
address in the first line of the mail header to whatever the
user gives as their mail address using the -f switch (read
sendmail documentation abuot this). This is mostly useful for
listservers that use this information for identification
purposes. It is strongly recommended that you use this
ONLY for mail that is going to a listserver or some other
mail robot.
- $listserver should be set to 1 if you are using the listserver
option described above. When this is set, the users from
address is concatenated to then $sendmail variable to produce
the actual command line option. Most people won't want to worry
about this.
- $script_http needs to be the http location of the script
so that it can find itself when the form is submitted.
- $script_loc should be the physical location of the script file
(if you intend to allow folks to grab the source code)
- If you want to log usage of the script, $logging should be
set to 1, and $logfile needs to be a filename that the http
daemon can write to. Otherwise, just uncomment both
lines.
As of version 1.3, you can restrict the mail addresses of sent mail
to a certain few, and you can even hide the addresses from the user
and give only real names or aliases. You can only do this if you are
running your own copy of the script. If you want to see what this looks
like, you can see an example here
Here's what you need to do to get it to work:
- Decide if you want to put the names and addresses in the source
or in an external file.
- If you want them in the source code, uncomment the lines that
define the %addrs hash, and changed the values to your
name/address pairs.
- If an external file is your pleasure, uncomment the lines below
the %addrs hash and change $mailto_addrs to the filename
(readable by the http daemon) containing the name/address.
You can learn about the format of this
file later.
- If you want the real mail addresses exposed, uncomment the line
that defines the value of $expose_address to 1.
Now when you access the URL, a selection list will be presented to the
user with a list of valid mail address. Only those mail addresses
are allowed to be used with this copy of the script -- any attempts to
change them will be rejected.
If you are using restricted mail addresses read from an external
file, as defined the the variable $mailto_addrs, you have to set up
the file in this way:
- In the defined file, each line should contain the name, any amount
of white space, then the mail address. There must be no white
space after the mail address -- a newline must follow! An
example is here.
- Make sure the file is readable by the user that your http daemon
runs as. World readable should always work.
- Added all kinds of robust error checking and reporting. Should
be easier to diagnose problems from the user end.
- New suggested sendmail flag -oi to keep sendmail from ending
mail input on line containing . only.
- Added support for setting the "real" From address in the first
line of the mail header using the -f sendmail switch. This may or may
not be what you want, depending on the application of the script.
This is useful for listservers that use that information for
identification purposes or whatever. This is NOT useful if you're
concerned about the security of your script for public usage. Your
mileage will vary, please read the sendmail manual about the -f
switch.
Thanks to Jeff
Lawrence (jlaw@irus.rri.uwo.ca) for figuring this one out.
New in version 2.0
I finally got off my butt and fixed this thing up to compete the
the current demands. It took about 20 pieces of mail and new from
various netters to get me to realized some of what they really want:
- ALL cgi varaibles (except those reserved for mail info) are
logged at then end of the mail received. You can put forms,
hidden data, or whatever you want, and the info for each
variable will get logged. Suppose you have a radio button
under the name "answer" with the options "Yes" and "No."
The logged data will look like this after the body of the mail:
answer -> Yes
It may also be desirable to just leave the body out all together
and just log other form data. It's up to you...
- Cleaned up a lot of spare code.
- IP addresses are now correctly logged instead of just hostnames.
- Made source retrieval optional. This could have been a small
security glitch on systems that don't want their code seen.
New in version 1.4
There's a couple new features (thanks to
Gabriel White)
and a couple of fixes in 1.4:
- You can now specify the next URL to be fetched after the mail
is sent in the CGI variable 'nexturl.' An example of this can
be seen at my home page - just send me mail, and you will get
a friendly response instead of the dry default confirmation.
- A Cc: field is presented, whose default value comes from the
CGI variable 'cc' (don't confuse with the compiler of the same
name!). It is only presented when a to-list selection is not
given.
- Fixed stupid HTML mistakes.
- Added "Send the mail" and "Start over" buttons to the top of the
form for extra convenience.
- User is fored to enter to enter something for the username in
the 'Your Email:' tag if identd (RFC 822) didn't get a username.
New in version 1.3
There are mainly enhancements to the enhancements in version 1.2.
- You can now give each address in the restricted address list a real name
or handle, which is the key in the associative array %addrs.
- You can define these names and addresses explicitly in the source code
or put them in a file. To define %addrs in the source code, uncomment
the appropriate lines, and fill in your own addresses. To define the
addresses in an external file:
- You have the option of specifying whether or not the user can actually
see the mail address associated with the names. This allows for
abstraction of where mail is really being sent. An example of
this can be seen here.
I hope everyone finds these enhancements useful. Thanks to Mathias Koerber
<Mathias.Koerber@swi.com.sg> for the ideas in versions 1.2 and 1.3.
New in version 1.2
The ability to place limits on where mail can be sent to has been
added to the script. Modifications are easy:
- Download the source code
here.
- Uncomment the lines that define the list @addrs, and change the
elements to whatever addresses are allowed.
- Change the ACTION tag in the FORM declaration for the POST method
to the URL of your copy of mailto.pl. Just string search for
ACTION and do what comes natually.
You can see an example of this here.
The choices listed are most of my effective e-mail address (which all get
forwarded to doug+@osu.edu anyway). If the CGI variable "to" is given
in URL (for GET method), then that address will be selected if it exists
in the list.
Also available now is a .forward file
and mail filter
that handles returned mail from the WWW Mail Gateway. Put
the .forward file in the home directory of the user who runs the http
daemon (do NOT put it in an active user's directory!!), change
the pathname where mailto.handler.pl exists and is executable,
and all mail returned mail will get shipped off the the real sender.
My server runs under the user "www" whose home directory is
"/usr/local/WWW" as is evident from the source code. If your server
runs as "nobody" and you don't want to change that, then you can make
a home directory for "nobody" and enable mail to that user. If your
server runs under your name, then all returned mail will get sent to
your account unless you figure out how to redirect only WWW Gateway
mail to the handler script. If the real sender's mail address is bad,
then the mail goes to the bit bucket.
If you find that someone is misusing this service, please report this
to me and/or the appropriate persons. This is intended to be useful
for everyone, not harmful. To help locate offenders, the custom header
X-Real-Host-From: is included in all outgoing mail which contains
the real hostname or IP address of the person using the service.
Doug Stevenson: doug+@osu.edu