Soupermail Email Tutorial

To:	everyone@everywhere
From:	vittal.aithal@bigfoot.com
Date:	$Date: 2001/02/02 00:48:22 $
Subject:	Soupermail Email Tutorial

Soupermail Email Tutorial

Soupermail's primary use is to generate an email based on form data. This tutorial is going to cover some basics of how Soupermail handles emails and formats their results. It assumes that you have installed Soupermail correctly, and that you have already succeeded in writing a working form with Soupermail. If you haven't, please do the Config File Tutorial. It is also helpful if you complete the Template Tutorial, as we'll be making an email template later on.

This tutorial has 8 steps and should take about 30 minutes to complete. It will be helpful to have 2 browser windows open while doing the tutorial, one to view this page with, and one to test your forms in.

Step 1

The first step is to learn that Soupermail treats the form field called Email in a very special way. Note that its Email, not email, or EMAIL, or e-mAiL, just Email with a capital 'E'. Read that sentence again and again until you understand that. The form field Email is considered to be the email address of the person filling in the form.

Step 2

Now, we'll make a simple form.

Make up a form like the one below, and save if as myemailform.htm on your server.

<html>
<body>
<form method="post" action="/cgi-bin/soupermail.pl">
Comments: <textarea name="comments"></textarea><br>
My email is <input type="text" name="Email"><br>
<input type="hidden" name="SoupermailConf" value="myemailconfig.txt">
<input type="submit">
</form>
</body>
</html>

Make sure that you change the form's action to the correct value for where Soupermail is installed on your server.

Note there are two fields in the form, a textarea called comments and the very special field called Email. We'll be using these in our template later on.

Step 3

Now, we'll make a config file for the form to use.

Make a file like the one below, and save it as myemailconfig.txt.

mailto: your_email_address@your_domain
subject: Email tutorial

Remember to change your_email_address@your_domain to be YOUR real email address.

Step 4

Now, go to the form, fill it in and submit it.

With any luck, you'll receive an email in the standard Soupermail format, with all the fields listed alphabetically, and some diagnostic information at the bottom.

The next few steps will cover changing the way this email is formatted.

Step 5

If you're happy receiving your form information as a list, but don't want the diagnostic information, you can use the config command nomailfooter: to control its appearance.

Open the myemailconfig.txt config file, and add the following line to it:

nomailfooter: yes

Save the modified config file back to the server and re-submit your form. If all goes well, you should see that the diagnostic information is gone.

Step 6

Now, we'll look at changing the default ordering of the fields. If you want the email fields to appear in the same order as they do on the form, we need to use the alphasort: config option.

Open the myemailconfig.txt config file, and add the following line to it:

alphasort: no

Save the modified config file back to the server and re-submit your form. Hopefully, the email you get back should have the comments before the email address.

Step 7

By now, you should have seen the basic email functions, but the best is yet to come. To fully customise your email, you need to make an email template.

Create a file like the one below, and save is as myemailtemplate.txt.

##############################################################################
# !!PING!! YOU HAVE MAIL(tm) FROM: <output name="Email">
##############################################################################

They said:
<output name="comments">
##############################################################################

Can you see the two output elements for the two form fields? Keep looking until you can, because its important to know that you need an output element for each form field that appears in the template.

Step 8

Now, we'll use the mailtemplate: config command to let Soupermail know it has to use our template. Add this line to the config file myemailconfig.txt.

mailtemplate: myemailtemplate.txt

Now return to the form, and re-submit it. You should now receive an email based on the template you've just written.

That completes this tutorial on email. Here are the files that were used:

Next Steps

There are a number of email templates you can use (such as sendertemplate), and they also have their HTML equivalents (such as htmlsendertemplate). You should read through the manual looking at the different types of template on offer, and try a few out.