Master Autoresponder Bank
(Version 1.3)

U s e r 's   M a n u a l

Requirements

To install and use Master Autoresponder Bank, these requirements must be met:

1. Your domain server must have Perl version 5+ installed, and have sendmail or qmail available.
    
2. If you're sending email to Master Autoresponder Bank, your server must be set up to relay/pipe the incoming email to the autoresponder script.
    
3. To install Master Autoresponder Bank, you must have and be able to use an FTP program for uploading files, creating directories, and changing permissions.
    
   CuteFTP and WS_FTP for Windows, and Transmit for Macintosh, are among the many FTP programs that allow you to CHMOD (change directory and file permissions). These are all available for download at http://tucows.com/

List of Files

{top}

Here is a list of the files you should have received when you generated Master Autoresponder Bank. Depending on how you generated your copy of Master Autoresponder Bank, the files with .cgi extensions may have .pl extensions instead.

LicenseAgreement.html
MABmanual.html
MasterAutoresponderBankControlPanel.cgi
MasterAutoresponderBankEmail.cgi
MasterAutoresponderBankForm.cgi
README.txt

Here are the files by category:

If you did not receive all of the above files, please write to us at programmer@willmaster.com — include a list of the files you did receive and the domain name Master Autoresponder Bank was generated for.

Getting Started

{top}

Creating directories
Installing the program
Setting permissions

      Creating directories

Master Autoresponder Bank is a set of programs. You'll probably want to create a directory within your "cgi-bin" to install Master Autoresponder Bank. This will allow you to keep the set of programs separate from other CGI programs you have installed or may install in the future. For example, you might name that directory: mab

When you first run the control panel, Master Autoresponder Bank will try to create a MABdata subdirectory. If it is successful in creating the subdirectory, it will also have correct permissions. If Master Autoresponder Bank can not create the subdirectory, you'll need to do create it manually and give the subdirectory MABdata global read/write permission. (See Setting permissions.) Note: Directory and file names are case sensitive.

The MABdata directory is where the Master Autoresponder Bank database and control panel password are located.

This is how the directory structure might look:

cgi-bin |
        | mab |
              | MABdata

Once installed in the mab directory, Master Autoresponder Bank will maintain data files in the MABdata directory.

{up}

{top}

      Installing the program

Upload the program files into the directory you decided upon above. Upload the files as ASCII/plain text and set file permissions (see Setting permissions) as indicated in the following table:

{up}

{top}

      Setting permissions

Permissions can be set via telnet or with some FTP programs. Here are the permission numbers translated into defining attributes:

The Control Panel

{top}

When you first type the URL of MasterAutoresponderBankControlPanel.cgi into your browser, you will be asked to provide a password. What you type here will be your password for future access to the Control Panel.

After the password screen, the main page will several links. Click "Configuration".

Here is a description of each section of the control panel's Configuration page:

General.

Maximum incoming email size.
If you wish to ignore incoming email larger than a certain size in kilobytes, specify that size here. Leave this blank to process all incoming email normally.

Location of sendmail.
Specify the location of sendmail on your server, or qmail if your server doesn't have sendmail. If using sendmail as the mailer, specify the -t flag. Example:

/sbin/sendmail/ -t

Email address database.
When an auto-response request is made, with a web page form or by email, the requester's email address can added to a database file. If you want such a file, type its name.

By default, the file you specify here will be put into subdirectory MABdata, where the password and global configuration files are. If you want the file in a different server location, type the directory with the file name.

Notification email address.
Specify where Master Autoresponder Bank emails notifications shall be sent to.

Form use notification.
Specify whether or not you want to be notified whenever someone uses a Master Autoresponder Bank web page form.

URL link "thank you" page.
When a Master Autoresponder Bank document request URL link is clicked, where shall the browser be redirected to? This is optional. The browser will be redirected to the domain's home page if no "thank you" page URL is provided here.

(A URL link is different than an email address link. A URL link opens a browser window to make the document request. One click does it. An email address link opens the email program in preparation to sending the request via email. The first click opens the email program; then, "send" must be clicked to send the email.)

Master Autoresponder Bank email address.
When someone sends an auto-response request email, what email address is it sent to?

Email use notification.
Specify whether or not you want a copy of the email when someone sends an email to Master Autoresponder Bank. If "yes," specify whether you want a copy of the email only when it is a valid request or a copy of every request. (Valid requests are considered to be those with the Master Autoresponder Bank email address on the To: header line.)

Outgoing Autoresponder Email.
(Master Autoresponder Bank will automatically put quotation marks around the names and angle brackets around the email addresses.)

From: name.
If you want a name in the From: header line of outgoing response email, type it here.

From: email address.
If you want an email address in the From: header line of outgoing response email, type it here.

Reply-To: name.
If you want a name in the Reply-To: header line of outgoing response email, type it here.

Reply-To: email address.
If you want an email address in the Reply-To: header line of outgoing response email, type it here.

Subject: header line.
If you want specific text in the Subject: header line of outgoing response email, type it here. You may use the [[filename]] placeholder to insert the requested file name. When the response is prepared for emailing, the [[filename]] placeholder will be replaced with the actual file name of the document being sent. Example:

Here is the [[filename]] document

Response Files.

Document directory location.
All documents that Master Autoresponder Bank will respond to must be in one directory. Type the complete server path to that directory location. (This is the server directory location, not the URL.) For security reasons, the program will not retrieve files from any other directory.

Maximum responses.
When a web page form is used, you can limit the number of files each form submission can request. There are several reasons one might want to do this.

1. When a large number of files are available on a form, choosing most or all of them could require the server to work several or many minutes to mail them all out. Limiting the number that can be requested with each form submission can reduce the impatience users might feel when a submission takes a large amount of time to process.

2. If a cracker should decide to send a large number of emails to someone the cracker dislikes or to someone who is adamantly anti-spam, the sense of harassment could be considerable. Limiting the number each submission can send might reduce the potential arguments.

Default response.
When an email arrives with a blank Subject line or with a Subject line that does not contain a valid file name, a default file can be specified. This file is then sent when no other is appropriate.

Global content header.
You can specify text to be placed above all response content, except the default file. With text email, the header will be inserted at the top of the content. With HTML email, the header will be inserted immediately below the BODY tag or, if that is missing, the HTML tag, so it appears at the top of the visible content.

Global content footer.
You can specify text to be placed below all response content, except the default file. With text email, the footer will be inserted at the bottom of the content. With HTML email, the footer will be inserted immediately above the closing /BODY tag or, if that is missing, the closing /HTML tag, so it appears at the bottom of the visible content. If neither closing /BODY tag nor closing /HTML tag are found in the file, the footer is omitted.

Notification email address.
Specify where Master Autoresponder Bank emails notifications shall be sent to.

Content file extension.
You may specify the file name extension if all response document files have the same extension. (The file name extension should begin with a period/dot character.) When no file name matches a request, the extension specified here will be applied and another match check done. Also, when the program generates a list of files available on request, it lists only files with the specified extension — unless no extension is specified here, in which case all files are listed.

Using the Program

{top}

Once the "Configuration" page of the control panel has been supplied with information, you're ready to use Master Autoresponder Bank.

Documents are retrieved from the document directory by file name and then emailed to the requester. If no document is available with the file name requested (or if no file was named), the default document file name is sent if one was specified in the control panel.

The default file can be a listing of documents available by autoresponder, or it can be anything else.

Master Autoresponder Bank assumes any email arriving without the correct email address in the To: header line is spam and will not respond to it. However, some spam is likely to arrive with the correct To: header line, and Master Autoresponder Bank won't know whether or not it is spam or a valid request.

Preparing document files.

Document files are plain text files. Format them the way you want them to be received by the requester.

Optionally, you can specify a From: email header line, a Reply-To: email header line, and/or a Subject: email header line within the document file. If you do specify any of the above, what you specify here will override what might have been specified in the control panel.

To specify any of the above header lines, they must be the first lines of the file and there must be at least one blank line following the header lines. Example:

To send HTML email, the <html> HTML tag must be the first word of the content. Example:

Four different placeholders may be put into document files. The placeholders will then be replaced with live data before emailing.

1. [[EMAIL]]
   Where you put that placeholder, Master Autoresponder Bank will insert the entire email that was received to be responded to.

2. [[FILE LIST]]
   Where you put that placeholder, Master Autoresponder Bank will insert a list of all documents available in the documents directory. If the control panel was used to specify a file name extension for document files, only files with that extension will be listed; otherwise, all files in that directory will be listed.

   If a response request email address was specified in the control panel, the file list will include clickable email links for requesting the individual files.

3. [[ATTACHMENT filename]]
   When you put that placeholder into the document file, Master Autoresponder Bank will retrieve the file specified by filename and attach it to the outgoing email. Example:

   From: "A Webmaster" <name@example.com> Subject: This is the one about how to win at checkers. The first move is what counts. ... ... ... [[ATTACHMENT stuff.pdf]]

   If the file to be attached is in the same directory as the document file, filename is specified as the name of the file to be attached — like in the example immediately above.

   If the file to be attached is in a subdirectory of the directory where the document file is at, filename the subdirectory name needs to be specified with the name of the file to be attached. Example:

   [[ATTACHMENT attachdir/stuff.pdf]]

   If the file to be attached is elsewhere on the server, filename the complete server directory path needs to be specified with the name of the file to be attached. Example:

   [[ATTACHMENT /www/attachments/stuff.pdf]]

4. [[TO]]
   The URL link method of requesting document files (see "Requesting document files" section below) requires the email address where the document is to be sent to. The URL link can be used anywhere, including in documents delivered by Master Autoresponder Bank.

   When a URL link is used in a document delivered by Master Autoresponder Bank, the placeholder [[TO]] is replaced with the address the document was sent to. This allows the requester to request another document, possibly the next in a series, by clicking on the link.

Requesting document files.

There are three ways to request document files, requesting one or more documents with a web page form, requesting a document with a URL link, and/or requesting a document by email.

1. By web page form.

Here is an example web page form:

The hidden field name="next" is the URL of the "thank you" page to display in the browser after the form is submitted.

The name of the checkbox form field is "file" and the value contains the file name of the document. Use as many as you need checkboxes. If you specified a content file name extension in the control panel, the file name extension in the checkbox value is optional.

The above HTML code creates a form that appears somewhat like this:

The program simply emails the file of every document requested.

A single document request form doesn't need the checkboxes. Instead, a hidden field name="file" specifies the file name of the document to send.

Here is an example:

The above HTML code creates a form that appears somewhat like this:

 
2. By URL link.

A URL link can be published for requesting a document. When clicked, it opens up the browser, sends the request to Master Autoresponder Bank, and displays a "thank you" page.

Here is the format of the URL:

__A__?email=__B__&file=__C__

The URL link method of requesting a document is an excellent way of providing access to additional documents from within one the recipient previously requested.

The URL link method can also be used in a newsletter and other publication where the recipient's email address can be inserted prior to or as it is being sent out. The software that sends the newsletter will need to insert the recipient's email address into the URL link.

If the URL of MasterAutoresponderBankForm.cgi is long, the URL link will be long. For this reason, it may be prudent to publish the URL link only in HTML email, where the URL is less likely to break and the link text can be short.

Here is an example URL link as it might be used in an HTML document sent by Master Autoresponder Bank.

In an HTML email, the above would appear somewhat like this (with an actual email address instead of "[[TO]]"):

When publishing URL links, the URL may not contain spaces. If the document file name in the URL contains spaces, replace each space with: %20 (For example, my file.txt would become my%20file.txt)

 
3. By email.

(See Requesting an Auto-Response By Email, below, for information about how to set up the server so it relays/pipes the Master Autoresponder Bank emails to the correct CGI program.)

An email sent to Master Autoresponder Bank can request a specific document file by specifying the file name in the Subject line of the email. The file name does not have to be the only text in the subject line. Other text can be there, too, so long as the file name is separated from other text by a space or other non-file name character. Here are examples with each Subject line requesting a file named hello.txt:

Subject: Send me file hello.txt
Subject: hello.txt
Subject: Oh, yeah! hello.txt is the one I want!

If no Subject line is sent with the email, or if Master Autoresponder Bank can't find a file name in the Subject line, the default file will be sent if one was specified in the control panel. If no file is available for sending, the program simply ignores the request.

Email links may be published. When an email link is clicked on, the user's email program opens up with an email ready for sending.

Here is the email link format:

mailto:__A__?subject=__B__

Here is an example email link as might be published in a plain text document file that Master Autoresponder Bank responds with.

Here is an example email link as might be published in an HTML document file that Master Autoresponder Bank responds with.

In an HTML email, the above would appear somewhat like this:

Email links may not contain spaces. If the subject in the link contains spaces, replace each space with: %20 (For example, ?subject=my file.txt would become ?subject=my%20file.txt)

Requesting an Auto-Response By Email

{top}

To request an auto response by email requires that your server relays/pipes the email to a script. The specific script is MasterAutoresponderBankEmail.cgi, included in the ZIP file when you generated Master Autoresponder Bank.

Some methods to relay/pipe email to a script are outlined below. These are generic instructions. Your hosting company might have different instructions or another method altogether.

Each of the methods below require that you know:

1. The server location of Perl (probably the same as the first line of Perl scripts, with the leading #! characters removed, but your hosting company might suggest a different location). For demonstration purposes, the instructions below will assume the location of Perl is
   /usr/bin/perl

2. The server location of the script MasterAutoresponderBankEmail.cgi. For demonstration purposes, the instructions below will assume the location of MasterAutoresponderBankEmail.cgi is
   /www/cgi-bin/mab/MasterAutoresponderBankEmail.cgi

   We'll also assume the email address for requesting an auto response from Master Autoresponder Bank is article@example.com

The example information
/usr/bin/perl /www/cgi-bin/mab/MasterAutoresponderBankEmail.cgi
used below is probably incorrect for your server. Substitute with the correct information.

 
Using cPanel:

This may be the easiest method. If you have cPanel, your version needs allows you to forward email to a script.

First, decide what email address you will use, if you haven't already. This would be the same email address as specified in the Master Autoresponder Bank control panel Configuration page, "General" section.

Find the section in cPanel where you forward individual email addresses (not the domain forwarder, but the forwarder for individual email addresses).

Where it asks for the email address to forward to, specify this, instead:

Some cPanel versions might not require the beginning and ending quotation marks. And some might not require the vertical bar character (following the leading quotation mark). But try it with the quotation marks and vertical bar character first.

 
Using the Unix .forward file:

With the .forward file, all incoming email is sent to MasterAutoresponderBankEmail.cgi. Thus, each arriving email launches the MasterAutoresponderBankEmail.cgi script, whether it's needed or not, and MasterAutoresponderBankEmail.cgi has to run in order to determine whether or not the email's "To:" header line contains a valid address.

When you upload or download any of the files mentioned here, use an FTP program and do the file transfer as ASCII/plain text (not as binary).

The .forward file resides in the server's root.

If the .forward file already exists and contains information, add this line to the bottom of the file:

If the .forward file does not exist, or if it is an empty file, create the file with this information (some assumptions are made):

The home@example.com line forwards a copy of all email received to home@example.com. That line may be removed. You can also add more email addresses on their own lines, if you want.

On the second line, replace username with your hosting account name. This may or may not be the same as your FTP username. Your hosting company can tell you. NOTE: The reverse slash in front of username must remain as the first character of the line. Also, any email addresses in the file should be above this line.

The last line is where the server is instructed to pipe a copy of the email to MasterAutoresponderBankEmail.cgi.

 
Using the sendmail aliases file:

With this method, you'll need to make an entry for each subscribe and each unsubscribe address your various autoresponders use. Simply add more entries as you create more autoresponders.

The aliases file usually resides in the /etc directory.

For article, add this line to the aliases file:

The part before the colon is the subscribe or unsubscribe address without the "@example.com" portion.

The above will pipe the emails that match the specified address to the MasterAutoresponderBankEmail.cgi script.

If you want to send an extra copy of the email to another address, put that email and a comma in front of the first quotation mark, like:

After adding or removing lines in the aliases file, you may need to run a server program to update the database for sendmail's use. Your hosting company can tell you whether or not that's required and what the program name would be.

 
Using the procmail procmailrc file:

Each entry in the procmailrc file is called a "recipe." Recipes take two or more lines. Comment lines that don't effect the recipe are lines beginning with a # character.

You'll need to make a recipe for the email address.

The procmailrc file usually resides in the /etc directory.

Add this recipe to the procmailrc file:

The above will pipe the article@example.com emails to the MasterAutoresponderBankEmail.cgi script. If you want a copy of the email piped instead of the original, put a character c at the end of the :0 lines, like:

Technical Support

{top}

Technical support is available. Please use the "Contact" or "Contact Us" link found at willmaster.com.

When asking for support, please include your domain name, a description of the problem, and any information you think might help us resolve the situation.

Professional installation for Master Autoresponder Bank is available. The form found with the "Contact" or "Contact Us" link at willmaster.com has a radio button to click when asking about software installation.

Thank you for your purchase of Master Autoresponder Bank.

Copyright 2003-2004,2006-2007 Bontrager Connection, LLC