+--------------------------------------------------+
|autoresponse - an autoresponder script for postfix|
|      Charles Hamilton - musashi@nefaria.com      |
|         This program is GNU/GPL software         |
+--------------------------------------------------+


+-----------------+
|Brief Description|
+-----------------+

Autoresponse is an autoresponder for postfix. It is part of the "postfix deployment tools" package
developed by Charles Hamilton however autoresponse can be used with just about any postfix setup.
The autoresponse script is called by postfix pipe(8) in the same way that one would call a content
filter. As a side note, it is possible to do some minor content filtering with this script however
that would require, at the least, intermediate level (or greater) knowledge of bash and some minor 
hacking of the autoresponse script--this will not be covered here. 

The command syntax for autoresponse is fairly straightforward:

autoresponse [-r {recipient email} -s {sender email} -S {sasl username} -C {client ip}] [-e {email address}] [-d {email address}] [-E {email address}] [-D {email address}] [-h] 

	-r, -s, -S, and optionally -C must be used together to specify a recipient, sender, sasl username, and client IP of an autoresponse message.
	   Normally you configure these in postfix's "master.cf" but they can be used from the terminal as well (only for testing purposes!).
	   If this is executed from a terminal, you'll need to hit CTRL-D when you are finished typing your autoresponse message.

	-e is used to create a new autoresponse or edit an existing one for the specified user. If a disabled
           autoresponse message exists, it will be ignored and a new message will be created.

	-d is used to disable an existing active autoresponse message.

	-E is used to enable an existing autoresponse message. If both a disabled AND and an active
           autoresponse message exist, the active message will be overwritten by the disabled one.

	-D is used to delete an existing autoresponse message, it will not delete disabled autoresponse messages.

	-h prints the autoresponse help menu.
	

+--------------------------+
|Installation/Configuration|
+--------------------------+

These instructions assume that SMTP authentication via SASL has
already been installed and configured (correctly) and SASL is running.

To install and configure, execute the following actions as root:

(1) useradd -d /var/spool/autoresponse -s `which nologin` autoresponse
(2) mkdir -p /var/spool/autoresponse/log /var/spool/autoresponse/responses
(3) cp ./autoresponse /usr/local/sbin/
(4) chown -R autoresponse.autoresponse /var/spool/autoresponse
(5) chmod -R 0770 /var/spool/autoresponse
(6) vi /etc/postfix/master.cf
(6a) Look for the following line:

smtp      inet  n       -       n       -       -       smtpd

(6b) And add the following line, directly below it (this line must begin with whitespace):

   -o content_filter=autoresponder:dummy

(6c) Add the following two lines (ensure the second one beings with
     whitespace) somewhere near the bottom of the file under the 
     section "# Other external delivery methods."

autoresponder unix - n n - - pipe
   flags=Fq user=autoresponse argv=/usr/local/sbin/autoresponse -s ${sender} -r ${original_recipient} -S ${sasl_username} -C ${client_address}

(6d) Save and quit

(7) Then run the following command :

	postconf -e 'autoresponder_destination_recipient_limit = 1'

(8) /etc/init.d/postfix restart


+-----------------+
|Additional notes:|
+-----------------+

[a] These steps are specific to Fedora however they will probably work on other distros as well.

[b] If you want local users to be able to create their own auto responses (from the shell), you 
    must put them in the 'autoresponse' group, see the manpage group(5) for instructions on how 
    to go about this.

[c] If step #7 seems counterintuitive, then see pipe(8) for more details. In a nutshell, it ensures
    that a message sent to multiple [valid] recipients will be recieved by everyone in the recipient
    list, rather than ONLY the first recipient in the list. If you still do not understand, skip step
    #7 and try sending a message with multiple recipients in the "to", "cc", etc fields. Note that only
    the first recipient in the list will actually recieve the message.

[d] For security reasons, SASL authentication is required in order to configure autoresponses via e-mail
    (You shouldn't be using unauthenticated SMTP anyway)


+---------------------------------------------------------------------------+
|Creating, disabling, enabling, and deleting autoresponse messages for users|
+---------------------------------------------------------------------------+

Via E-mail:
-----------

To create an autoresponse message for a user via e-mail, just send an e-mail to
"user+autoresponse@domain.tld" where 'user' is the user portion of the e-mail address
for the user that you are setting the autoresponse message. The message must originate 
from "user@domain.tld" (for obvious reasons) otherwise an autoresponse will not be 
created. If you have a pre-existing autoresponse message, it will be deleted and the 
user will be notified that the autoresponse message has been disabled. Think of it as 
a toggle switch. If you do not have a pre-existing autoresponse message, the  message 
you send will now become your autoresponse---basically, you'll want to format the 
message exactly as you'd like for it to appear; WYSIWYG (What You Send Is What You Get).

Via the shell:
--------------

To create an autoresponse message for a user, invoke the following command from the shell:

	autoresponse -e user@domain.tld

Where 'user@domain.tld' is the e-mail address of the user who requires an autoresponse. Upon
running this command, the vi editor will open; just type the user's autoresponse, save and 
quit as you normally would with any text file. That's all you have to do.

To disable an autoresponse message for a user:

	autoresponse -d user@domain.tld

To enable an autoresponse message for a user:

	autoresponse -E user@domain.tld

To delete an autoresponse message for a user:

	autoresponse -D user@domain.tld

###UPDATE 6/12/2009###
Fixed an issue with "case sensitive" e-mail addresses. Basically,
UsEr@domain.tld or USER@DOMAIN.TLD --- both valid addresses, were not able
to set an autoresponse message for user@domain.tld.

###UPDATE 4/2/2009###
Autoresponse has a tutorial on HowToForge:
http://www.howtoforge.com/how-to-set-up-a-postfix-autoresponder-with-autoresponse

###UPDATE 3/19/2009 v. 1.6.2###
Fixed a minor bug that could potentially 
cause the message body of an autoresponse 
to contain text that wasn't intended.

### UPDATE 7/3/2009 ###
SMTP authentication via SASL is now required!

### UPDATE 2/2/2009 ###
Made a few efficiency-oriented modifications

### UPDATE 10/17/2008 ###
Fixed an issue with the Return-Path header being set
to the address of the autoresponse user rather than the
address of the original sender of the message (thanks go 
to Richard Mulder for catching this).
