Using e-merge requires two or three files, depending on whether you want to log the user input or not. The files are all simple text files with fairly straighforward formats.
Build an HTML file with a normal HTML form, using either POST or GET methods (POST method is preferred these days, but e-merge doesn't actually care). The only requirement for your form is that any fields which you want to force the user to fill out before mailing should be named 'required-name' (the dash after 'required' is essential). The action of the form should be pointed to e-merge with the web server (virtual) path to the merge file appended. If you wish to log users' input, tack on &log or &log=/another/virtual/path.log. If you just put &log, e-merge will assume your log file is named the same as your merge file, but with a .log extension. If you specify a path, it will use that file for logging. You can also specify a display file by adding &display or &display=/yet/another/virtual/path, with the same rules as for the log file. Example
You can run e-merge in testing mode by adding &test to the end of the ACTION line. When in testing mode, e-merge will not actually send any mail or write to a log file. Thus, you can see what e-merge's output will look like without cluttering up an e-mail account.
The merge file specifies the format in which your mail will be sent. The first few lines of this file are very important, as they must be valid mail headers. Following the headers, there should be a blank line and then the format/content of your message.
The input from the HTML form can be included in any part of the merge file by bracketing the HTML form field name between square brackets [ ] (eg: [address]). Fields can be included anywhere in the merge file. Oh, I almost forgot to mention: e-merge can also include the web server CGI environment variables as fields. To use an environment variable as a field, put the name of the variable, preceded by a dollar sign ($), surrounded by brackets [ ]. One of my favorites is the environment variable $HTTP_REFERER, which will contain the URL of the form from which the message was sent.
The first few lines of your merge file should be mail headers. You definitely need to have a 'To: ' header and a 'From: ' header, and you'll usually want a 'Subject: ' header as well. If you allow the 'To: ' header to be filled in with input from the form, you should probably include an 'Errors-To: ' header with an address which cannot be modified by the user. Following the mail headers, you should include a blank line to separate the headers from the body of the message. Now I realize that you could write your own totally bogus mail headers and pretend to send e-mail as someone else, but I know that you're all far too honest for that sort of thing (and besides, it's so easy to do by other means anyways).
The body of the message can be in any form you like. Since the formatted mail message will be echoed to the user's web browser as HTML, you can use HTML markup with links, formatting, etc. You may want to include a note in the mail saying that the mail came from the world wide web and that it's origin can't be verified. Example
The display file allows you to control the appearance of the page that appears after the mail has been sent. In cgiemail and earlier versions of e-merge, the page displayed after the mail was sent was simply a copy of the mail message that went out, and e-merge will now default to this if no display file is specified. However, you can now use a display file which will have the form fields merged into it just like the merge file, and it will be displayed instead of the mail message. This allows you to create some very nice response pages with any HTML markup you like. The format of the display file is simply an HTML page with [fieldname] inserted wherever you wish a form field's data to be displayed. Example
The log file is often not necessary, since logging is not always desired. It can also be automatically created under certain circumstances on the web server (if the user who the web server runs as -- frequently nobody -- has write access to the directory you want to write the log file to). If present, the log file should contain a list of fields in the first line of the file. The fields should not be surrounded by brackets [ ] and should be tab separated. e-merge will read the first line of the log file to determine which fields to log and what order to log them in. In order for the logging to take place, make sure that the log file is able to be written by the web server. Example
e-merge's ~username handling mechanism is something of a hack. You can only use ~username directory references if your merge file is specified with one. As long as the merge file uses ~username and the server expands that properly, then it is okay to use ~username (with the same username only) for the log and display files. It would be a drag for e-merge to have to find the server config files and get data from the passwd file in order to handle this all perfectly, and I think that the current mechanism is very useable and should cover most situations.
e-merge does some magic when it sees that the user has entered multiple values for a given field (like checkboxes or multiple-select list boxes). It looks through the merge file to see if the field has been listed on a line by itself or is preceded by a title. If it's on a line by itself, e-merge figures that you want to have a list of the selections, each on their own line. If there was whitespace on the line before the field, it will be included before each element of the input. If the field is preceded by a title, e-merge assumes you want a comma separated list (on the same line as the title).
e-merge also does a bit a smaller magic if you indicate that you want to use logging or a disply file, but do not specify a file (by using &log without the =/path part), e-merge strips the filename extension from the merge file (if there is one), and adds .log or .display.