#################################################################
This is simplemail.mv. A user-friendly Miva script to process
mail generated by a plain HTML form that you create.
Copyright 1998-1999 Simple Network Communications, Inc.
Copyright 1999-2000 Yahoo!, Inc.
All rights reserved.
Developed on Miva Version 3.2211, November 1998 by
Doug Barton, DougB@yahoo-inc.com.
Release Version 1.6
Fully backwards compatible with previous SimpleMail versions.
Now requires version 3.5 or greater of the Miva engine.
Changelog:
==========
Version 1.6, December 2000
1. Remove now-gratuitous whitespace reducing macros
and use the compresswhitespace option instead.
2. Handle formatting of e-mail slightly differently
so that the result looks the same as it used to.
3. Miscellaneous HTML and other cleanups.
Version 1.5, March 2000
1. Remove Track-star banner
Version 1.4, July 1999
1. Be even more cautious about From: e-mail addresses.
2. Strip spaces from URL's before db creation.
3. Improve performance on form submission error checking.
Version 1.3, May 1999
1. Changed default From: address to first To: address to avoid
remote sites rejecting the mail because of the fictitious From:.
2. Added target attributes to form and help URL's.
3. Converted to Miva's new (in 3.5) builtin isdigit() function.
Version 1.2, March 1999
1. Fixed typo in e-mail address test.
Version 1.1, January 1999
1. Improved documentation in response to user suggestions.
2. Made error messages more informative.
3. Slightly improved efficiency of form processing and
database creation.
4. Added feature: "Is it an IP address?" attribute.
5. Added feature: If you use a custom response form, SimpleMail
will use a META "refresh" tag to display it. This is both
more efficient and helps hide the existence of SimpleMail
from the end user. This feature can be turned off in the
database modification form.
#################################################################
First set some variables that we will use often
SimpleMail Administration
End users don't need to know where they came from if there is an error.
"Main" loop to decide which subprocess to start.
End of the "Main" loop
First, open up the databases and check the attributes of the individual
fields. If we find an error, send them to either a custom error URL
provided by the user, or display the default error message.
If there was an error opening the databases, let the user know
Loop through attributes database and test end user's input
Use nested IF's to improve performance since Miva tests
both sides of an AND test even if the first fails
Test to see if the value is mandatoryNow test the other values only if they exist
Ok, we didn't find any errors there, so let's get ready to send the mail
Loop through the attributes database replacing any &variable tags in the
subject line or body with the value of that variable.
Either use the plain text From: address from the db, or test the address
entered by a user into an email field.
Your form has been processed
successfully. Thank you.
Your form has been processed
successfully. Thank you.
Loop through and replace all combinations of hard returns from various
platforms so we can output the text from the message body to a file.
Squish double tokens into one so that if the user has a hard return
in their message body we get the whole message, and DOS users will
have two anyway.
Error:
Unfortunately, there was an error in the processing of your
form. Please send an e-mail to
&[SM_admin_db.d.SM_email:entities] with the following information:
URL of the form:
Error message:
Thank you for your patience, and sorry for any inconvenience.
Smash the URL into a database filename
Take an incoming string that should contain an e-mail address or addresses
and format it for use with strict address format checking.
First, convert tab to space, just in case they got one in there somehow.
Be super paranoid, smash extra spaces
Now convert single spaces to commas
Just in case something weird happened, turn double commas into single
Now we take the comma delimited list and make sure every item is valid
and is enclosed in angle brackets.
Strip the trailing comma for neatness' sake
Form Error
One or more of the fields that you entered into the form was not correct.
Here is a summary of the errors:
Please use your browser's [Back] button to return to the form and correct
any errors.
Main Menu
Welcome to SimpleMail administration. You may choose from the following:
Create a new form database
Modify an existing form database
Delete an existing form database
Delete your SimpleMail installation
Change the administrator name and/or password
Or, you may choose to modify the database of one of the existing
forms below by clicking on its link:
This assignment would not be necessary except that Miva doesn't like tags within an IF
Welcome. Please enter your username and password.
Choose a form database for deletion:
Choose a form database for modification:
Give the user a custom message depending on how we got here.
Error:
There was an error in one or more of the fields you entered, so your form
database has not yet been updated. Please take a look at the fields
below, correct any errors, re-enter your other changes and resubmit this form. your form
database has not yet been updated
Form Database Creation
Caution:
You asked to create a new database for the form listed below, however a
database for that form already exists. Never fear though, you can make your
changes here and the database for this form will be updated with your
new values.
Caution:
Form Database Creation
The form database for the URL listed below has been created successfully.
Form Database Modification
The information below comes from the database for the HTML mail form listed.
If you would like to make any changes to your formatting or other form
attributes you can do so on this form and push the "Save"
button at the bottom of this form. If you make any changes
to your form database here, make sure that all of your
information is correct because the database will be recreated with the
values shown here.
anyall
If you are happy with the attributes of the form as listed, you can push
the "Go to the main administration menu" button at the bottom of
the form and no changes will be made.
If you change the name of a variable
in your form, you must recreate the database for that form.
When your user completes your form and an e-mail to you is generated by SimpleMail
they are sent by default to a one line page with the words, "Your form has been processed
successfully. Thank you." If you would like to send them to a page of
your own instead, specify it here.
If you plan to use a customized response page make sure that you specify
the complete URL, including
Response URL:
By default SimpleMail will use a META "refresh" tag to send users to
your response page if you include one. Very old browsers do not know how to
process that tag, so they will see the standard SimpleMail response page instead of
your custom one. If you would rather not use the "refresh" tag, check this
box.
Do not use META "refresh" to show my custom
response page
If you would like to specify a URL for an error reply to your users, enter
it here. If there is no page specified, the default error form will be used
as described in the
form creation help file.
If you plan to use a customized error page make sure that you specify
the complete URL, including
Error URL:
SimpleMail can customize the value of the From: e-mail address and
Subject: line in the e-mail that you receive after users POST mail from
your form. Either or both lines can be plain text that you specify here,
variables that you use in your form, or in the Subject: a combination of both.
If you would
like to use a plain text string, you can enter it directly into this form
below. You can use the value of a variable from your form by
putting an ampersand (&) before the variable name. For example
if you want the From: e-mail address to be the variable called
"users_email" from your form, you would put this in the form below:
&users_email
Please be aware that the From: e-mail field can only have ONE e-mail
address, and no additional plain text. If you use a variable from your form
make sure to add the "E-mail" and "Mandatory" attributes
to that variable in the attributes section below. Otherwise Miva will not
send mail from your form.
The From: and Subject: lines must be filled in with something in order
for Miva to send your mail. If you are not concerned with what appears in
those fields on the e-mail you receive the following default text will be
filled in for you.
E-mail "From:" address:
E-mail "Subject:" line:
In addition to sending e-mail to the account you specify SimpleMail can
save a copy of each mail it sends to a file. The files for this form will be
saved in the
directory, which will be within the mivadata directory in your account.
Save mail to a file:
Attributes:
The individual variables from your form can have the following
attributes. Is the variable Mandatory? Is the variable a Numeric
field? Is it an E-mail address? And does that field contain an
IP address? Specifying that
a variable is both an e-mail address and a number would not be very useful. :)
If a user of your form enters information which
does not match the attributes for that field specified here
SimpleMail will send that user an error indicating what information needs
to be changed, either through the default error form or through a form
that you specify above.
Form variable
Mandatory
Numeric
E-Mail
IP
Below is the existing format for the e-mail that will be sent when
the form at is POST'ed to
SimpleMail. You can modify this formatting two ways. First, by adding plain
text that you want to see in the e-mail you receive at any point in the
editing window below. Second, wherever you want the value of a variable name
from your form displayed, add an ampersand (&) to the front of the variable:
&your_variable_name
SimpleMail will convert that to
the value of the variable with that name. For instance, if your variable
had the name "product_line," which contains the name of -- you
guessed it -- one of your product lines, you would use a line like this:
Product line: &product_line
This will display the following text in the e-mail you receive
if the user filling out your form enters "Long handled brushes"
as the product line he or she is interested in:
Product line: Long handled brushes
Caution: Miva uses an XML (eXtensible
Markup Language) script interpreter that works like HTML.
Therefore you must make sure that any plain text you enter does not contain
the HTML formatting characters <, >, &, or ". You should
also use caution with characters like ( ), and { } because Miva uses them internally.
Edit your formatting here:
Old database deleted successfully
Error:
There was an error deleting the form databases for the form at . You should take a look
at the directory under your mivadata
directory in your account and delete:
mivadata
Then you should be able to resume the operation you were attempting when
this error occured.
If you need assistance please feel free to contact Customer Support.
List of databases updated successfully Check the destination e-mail address Check the optional response page URL Check the optional error page URL
form creation help file for details.">
If the user put something in the From: e-mail address category, check to see
if it's a variable or if it's a plain text e-mail address. If it's plain
text, check to make sure there is just one address, and that it's valid,
then return with the formatted address to enter into the database.
If we found an error above, make a note so that we can send them back
to the input screen after saving the valid responses.
Start the process of creating new databases with the new info. First
the main form db then the attribute db.
Save this value before we wipe the old db. This value is always good
For the rest, if there is no error, save the value. If there is an error,
we will give them another chance below.
Read in their form, creating the attributes database with the new values.
By using MvCreate it will delete the old one.
Assign temp variables to the attribute + name pair because Miva won't
doubly de-reference variables.
Just assign the value. It will either be "1" because that's the value
from the form above, or "NULL" which != 1 so the boolean value of
this field will still be valid.
If this value still exists it means there was an error.
Set the default value again for safety or else they won't be able to send mail.
Now that the new databases for this form have been created, add the encoded
name of the form to the "list of forms" database so we can use it later.
Delete any occurrence of the form that's already there
If there was an error creating the databases, let the user know
Error:
Unfortunately, there was an error in the process of creating your
mail form databases. The following errors were generated:
If you need assistance please feel free to contact Customer Support.
Since this isn't a fatal error (just an annoyance) let everything else
get updated (because it was deleted previously) but let the user know
there was an error so they can fix it if desired.
As advertised, send them back to correct the error if one exists.
Otherwise, it's all good so back to the main admin menu
Form database updated successfully
Start the process of creating the actual databases. First the main form db
then the attribute db.
Read in their form, populate the formatting part of the database with basic
defaults to get them started, and create the attributes database.
Error:
The variable named ""
from your form contains an invalid character. The only valid
characters for the names of form variables are A-Z, a-z, 0-9
and '_' (underscore).
Please change the name of this variable, and any others that have
invalid characters and return to the form database creation process.
Now that the new databases for this form have been created, add the encoded
name of the form to the "list of forms" database so we can use it later.
Delete any occurrence of the form that's already there
If there was an error creating the databases, let the user know
Error:
Unfortunately, there was an error in the process of creating your
mail form databases. The following errors were generated:
If you need assistance please feel free to contact Customer Support.
Strip spaces for safety
First check the main form URL
If everything is OK this error will be unset
Now check the destination e-mail address
If we found an error, send them back to the input screen
Otherwise, check to see if we are creating a new db or gonna read in
an old one.
Setting up a new form
There are two essential items needed to set up a new form for use
with SimpleMail. All information related to a given mail form will be
referred to in the database by the URL of your form. Therefore before you
start the setup process the form must be uploaded to your account, and
you should make a note of the complete URL. essential
If you have not yet set up a mail form for use with SimpleMail,
please take a moment to look at the help file to familiarize yourself
with the basics.
Next, you need to know the e-mail address or addresses to which your mail
from this form will be sent. You MUST set the e-mail destination
for this form in the database. Creating a form that sends mail to random
destinations is a violation of our Acceptable Use Policy for your account.
If you are ready to start the process of creating a database for your form,
enter the URL here. Because of the way that certain browsers handle the
'http_referer' variable it is highly recommended that you not put
your form on the index page in any document directory. It is better to put a link
from the index page to the page which will have your form.
URL of your form:
Destination E-mail:
Basic steps for mail form setup
For your convenience we have created a system that allows you to create
a simple HTML mail form that will interact with the SimpleMail script in
such a way that you do not need to do any CGI/Miva coding yourself. The
only requirement is for you to add the line described below as the FORM
tag in your HTML mail form. This tells your user's browser where to send
the mail, namely to your SimpleMail script.
Your FORM tag must look EXACTLY like this. If you use
something different it will not work.
<FORM method="POST" action="&[SM_documenturl]">
You can use almost any label for the name=" " variables in your
HTML form; however your variable names must not begin with the characters,
"SM_" or they will conflict with the internal SimpleMail variables.
Also, Miva requires that all variable
names contain only the characters A-Z, a-z, 0-9, and '_' (underscore).
Unfortunately, due to limitations in Miva you cannot use CGI tags where
the input type is an image or a file, and if you use a <select> tag
you cannot use the "multiple" attribute in that tag.
Because of the way that certain browsers handle the 'http_referer' variable
it is highly recommended that you not put your form on the index page in
any document directory. It is better to put a link from the index page to the page
which will have your form. Also, you will get better results if you use only one
form per HTML page.
If you change the name of a variable
in your form, you must recreate the database for that form.
Simple mail form
This is an extremely basic mail form, including the FORM line described above:
<HTML>
<HEAD>
<TITLE>Very Simple Mail Form</TITLE>
</HEAD>
<BODY>
This is my very simple mail form
<!-- The line below is essential and must be included -->
<FORM method="POST" action="&[SM_documenturl]">
<P>Put your message here:<BR>
<textarea name="users_message" cols="70"
rows="10"></textarea>
<P><input type="submit" value="Send my mail">
</FORM>
</BODY>
</HTML>
You can copy the above text and paste it into a file which you can
upload to your account. This will give you a basic idea of how the
form works together with SimpleMail. Make sure that you save your file as
plain text, sometimes called ASCII text.
Simple error form
You can specify that fields in your form have certain properties in the
form database. If your user enters something in your form that does not
match the attributes you have specified, they will receive an error
message from a URL whose HTML source looks like this:
<HTML>
<HEAD>
<TITLE>Form Error</TITLE>
</HEAD>
<BODY bgcolor="#FFFFFF">
<Center><H1><font color="#FF0000">Form Error</font></H1></Center>
One or more of the fields that you entered into the form was not correct.
Here is a summary of the errors:
<P><blockquote>
##List of errors here##
</blockquote>
Please use your browser's [Back] button to return to the form
and correct any errors.
</BODY>
</HTML>
If you would like to specify that your user receive a customized
error message you can create a page with source similar to the one above
and specify the URL in your form database. Wherever you place the
"##List of errors here##" pseudo-tag it will be replaced with
the actual list of errors generated by the user's input.
If you choose to make a field mandatory, you should give special
attention to the name of that field. Your user will receive an error
message similar to:
This field is mandatory: users_email
If the name of the field is not fairly self-explanatory your user may become
confused as to which field was not filled in properly.
You can use this error form as a sample like the sample mail form above
if you would like to see how it works. However an error URL is
not mandatory if the simple message above is sufficient for
your needs.
Error:
There was an error creating the ""
directory within your mivadata directory. This is an essential
step for SimpleMail setup.
If you need assistance please feel free to contact Customer Support.
Test the values for errors
Error:
Unfortunately, there was an error in the process of deleting your
administration database.
If you need assistance please feel free to contact Customer Support.
Please correct this error and try again.
If you need assistance please feel free to contact Customer Support.
Step One:
Your administrator database has been created with the following values:
Now that you have administrator access to your mail system, your next step
is to set up a SimpleMail database for your HTML mail form.
Administrator Database Creation
It is very important that you remember your
password because you will not be able to retrieve it from the database in a
form that you can read. very important
The name you choose here will never be displayed to users. It is
only used to identify you to the SimpleMail administration password validator.
If an error is generated by SimpleMail from input POST'ed to it by your
form, the e-mail address you enter here will be displayed with an informative
message telling the user to mail you.
Username:
Password:
Re-type Password:
E-mail:
Since no admin database exists yet, and we want to use the same
code to create a new db as we do to change an existing one, we
need to prime the pump with something, so we fake one up.
Error:
There was an error creating the
directory within your mivadata directory. This is an essential
step for SimpleMail setup. mivadata
If you need assistance please feel free to contact Customer Support.
Please correct this error and try again.
If you need assistance please feel free to contact Customer Support.
First time setup for administrators
If this is the very first time you have ever run SimpleMail,
or your previous SimpleMail administration files have somehow been deleted,
this page is the first step in setting up your installation. very first
Please bookmark this page now so that you
can return later if you need to add forms or make changes.
The SimpleMail script creates a database for each form which you wish to
receive mail from. That database holds all of the information about your
form, including how and where to send the mail.
Because SimpleMail uses the URL of your form to identify the information
related to it in the database, before you can add a mail form for processing
you must create the form and upload it to your account. If you have
not already, please take a minute to view the help page, then return here
and continue your setup.
Step One:
If you have a mail form ready to go, the first thing you need to do is
to choose a name and password for the SimpleMail administrator.
Uninstall
All possible SimpleMail files have been deleted. At this time, it is not
possible for Miva to delete directories,
so if you want to delete the directory
that is currently in the mivadata directory on your account, you
will have to do that by hand. mivadata
Unfortunately there was a problem deleting the following files in
the directory. You will have to remove
them by hand.
If you need assistance please feel free to contact Customer Support.
We hope you enjoyed using SimpleMail.
Are you SURE?
If you delete your SimpleMail installation ALL of your
SimpleMail database files will be permanently deleted. Although there will
be no way to recover any of the database files; your mail forms, the
SimpleMail script itself and any text copies of mail sent by SimpleMail
will not be deleted. ALL
If deleting SimpleMail is not what you had in mind, you should hit the
[Back] button on your browser now.
If you are really really sure that this is what you want to do,
press the button.