.TH autoresponder 1 "August 2002" "" "MeepZor Utilities" .\" Copyright (c) 2000-2002, MeepZor Consulting. .\" All rights reserved. .\" .\" The use and distribution of this code or document is .\" governed by version 1.0.1 of the MeepZor Consulting Public .\" Licence (MCPL), which may be found on the Internet at .\" . .\" .SH "NAME" autoresponder \- An Email Receptionist .SH "SYNOPSIS" .B autoresponder \fB\--from\fP \fIemail-address\fP [\fB\--accept-for\fP \fIpattern\fP] [\fB\--bcc\fP \fIaddress-list\fP] [\fB\--cc\fP \fIaddress-list\fP] [\fB\--edit-response\fP] [\fB\--errors-to\fP \fIaddress-list\fP] [\fB\--file\fP \fIreply-text-file\fP] [\fB\--history-add\fP \fIemail-address\fP] [\fB\--history-db\fP \fIdatabase-file\fP] [\fB\--history-list\fP] [\fB\--history-remove\fP \fIemail-address\fP] [\fB\--ignore-from\fP \fIpattern\fP] [\fB\--ignore-header\fP \fIfieldname:pattern\fP] [\fB\--ignore-interval\fP \fIseconds\fP] [\fB\--ignore-precedence\fP \fIpattern\fP] [\fB\--ignore-subject\fP \fIpattern\fP] [\fB\--[no]include-original\fP] [\fB\--precedence\fP \fImailpri\fP] [\fB\--rc-file\fP \fIfilename\fP] [\fB\--sender\fP \fIemail-address\fP] [\fB\--subject\fP \fIprintf-string\fP] [\fB\--[no]verbose\fP] [\fB\--version\fP] [\fB\--work-dir\fP \fIdirectory\fP] .br .SH "DESCRIPTION" .B autoresponder is a rather hackish script to deal with incoming mail; a sort of email receptionist. It sends a standard reply back to the sender. It's designed to be invoked through \fI.forward\fP or \fI.qmail\fP files. .SH "OPTION SYNTAX" Option values may be separated from their keywords by either an equals-sign ('=') or a space; the following are equivalent: .IP "\fB\--from john.doe@nowhere.com\fP" .IP "\fB\--from=john.doe@nowhere.com\fP" .P Options are taken from the command line. If a \fI~/.autoresponderrc\fP file exists, its contents are read and prefixed to the command line arguments. Blank lines, lines containing only whitespace, and lines beginning with a '#' (with or without leading whitespace) are treated as comments and ignored. The effect is equivalent to .P \fBautoresponder `cat ~/.autoresponderrc` \fP\fIcommand-line-args\fP .P As a consequence, options in the \fI~/.autoresponderrc\fP file may be specified either as one per line or multiple options per line, but '\e' continuation characters should \fBnot\fP be used. .P Some options may appear on the command line more than once, such as .IP "\fB--ignore-from foo --ignore-from bar\fP" .PP The individual option descriptions indicate whether this applies. .P .SH "OPTIONS" .IP "--from \fIemail-address\fP" The address to put into the 'From:' field of the response. Mail settings may prevent this from taking effect if this is not the same as the actually responding account; some systems take a dim view of such masquerades. This option may occur multiple times. \fBNote:\fP This option is \fIrequired\fP. .IP "--accept-for \fIpattern\fP" Only reply if one or more of the specified regular expressions appears in the original message's \fITo:\fP or \fICc:\fP fields. In other words, don't reply to blind mailings. The default is to reply regardless of the recipient of the original message. \fBUse this option with care, since it can block messages from mailing lists to which you are subscribed!\fP This option may occur multiple times. .IP "--bcc \fIaddress-list\fP" A comma-separated list of addresses to include in the response's Bcc field. The default is to have no Bcc list. .IP "--cc \fIaddress-list\fP" A comma-separated list of addresses to include in the response's Cc field. The default is to have no Cc list. .IP "--edit-response" Indicates that the contents of the response file (\fB--file\fP) should be modified and substitutions applied. If the file contains any of the following special sequences, they will be replaced as described: .RS .IP "\fB%F\fP" Replaced by the eddress information of the sender of the original message. .IP "\fB%L\fP" The current local time is substituted. The offset from Universal is included. .IP "\fB%S\fP" 4 Replaced by the original subject of the message (after any reply prefixes have been removed). .IP "\fB%T\fP" Replaced by the eddress to which the original message was sent. .IP "\fB%U\fP" The current Universal (GMT) time is substituted. .RE .PP Time values are formatted with \fBstrftime\fP(3) using "%a, %d %b %Y %T"; this is based on the HTTP standard date syntax. \fB%U\fP string will have "GMT" appended, and \fB%L\fP string will have the local offset from Universal time appended (\fIe.g.\fP, "-0800"). .PP \fBNote:\fP For large response files this option can have a significant impact on the script's performance. .IP "--errors-to \fIaddress-list\fP" A comma-separated list of addresses to include in the response's Errors-To field; these should receive notification of any problems if the response doesn't reach its destination. The default is to have no Errors-To list. \fBNote:\fP This header field is somewhat controversial, and may be ignored by many systems, which will use the one of the "From:", "From", or "Sender:" field values to report errors. .IP "--file \fIreply-text-file\fP" The name of the file comprising the response text. Only text files are supported at this time. If omitted, the reply text sent is: .br .br This is an automatic response. Your message has been received. .IP "--history-add \fIemail-address\fP" Adds the specified email address to the do-not-reply history database. The entry will be eligible for removal after the number of seconds specified by the \fI--ignore-interval\fP option. Only other history database options will be processed. Requires that the \fI--history-db\fP option be specified. This option may occur multiple times. .IP "--history-db \fIhistory-file\fP" Specifies the name of an SDBM database to use to track responses so that a flood of inbound messages from the same address won't result in an equal-sized flood of outbound autoresponses. Include the directory path, but do \fBnot\fP specify the \fI.pag\fP or \fI\?.\?dir\fP suffix. .IP "--history-list" Displays the entries in the do-not-reply history database and when they become eligible to receive autoresponses. Only other history database options will be processed. Requires that the \fI--history-db\fP option be specified. .IP "--history-remove \fIemail-address\fP" Removes the specified address from the do-not-reply database. The address immediately becomes eligible to receive autoresponses. Only other history database options will be processed. Requires that the \fI--history-db\fP option be specified. This option may occur multiple times. .IP "--ignore-from \fIpattern\fP" Specifies a regular expression pattern (see 'man perlre') used to match origins to which replies should \fBnot\fP be sent. Matches are performed in a case-INSENSITIVE manner. This option may occur multiple times. .IP "--ignore-header \fIfieldname:pattern\fP" Identifies the name of a field in the message header, and a regular expression pattern (see 'man perlre') against which to compare its value. If a match is detected, an autoresponse is \fBnot\fP sent. Matches are performed in a case-INSENSITIVE manner. This option may occur multiple times. .IP "--ignore-interval \fIseconds\fP" If history tracking is enabled, this value specifies the minimum number of seconds that must pass before another autoresponse will be sent to the same source address. For normal operations the minimum value allowed is 30 seconds; When used with \fI--history-add\fP, the minimum value is 0 (meaning never send an autoresponse). If omitted, the default is the minimum. .IP "--ignore-precedence \fIpattern\fP" Specifies a regular expression pattern (see 'man perlre') used to match message precedences to which replies should \fBnot\fP be sent. This option may occur multiple times. Matches are performed in a case-INSENSITIVE manner. This option may occur multiple times. .IP "--ignore-subject \fIpattern\fP" Specifies a regular expression pattern (see 'man perlre') used to match the subjects of messages to which replies should \fBnot\fP be sent. This option may occur multiple times. Matches are performed in a case-INSENSITIVE manner. This option may occur multiple times. .IP "--[no]include-original" Indicates whether or not the original message should be included in the response as a MIME attachment. The default is to not attach the original message. .IP "--no-reply-to \fIpattern\fP" Deprecated in release 1.11. Use \fI\--ignore-from\fP instead. .IP "--precedence \fImailpri\fP" Specifies the precedence of the autoresponse message. The default value is "bulk". .IP "--[no]rc-file \fIfilename\fP" Specifies a file of options to be used instead of \fI$HOME/.autoresponderrc\fP. Useful only on the command line, not in an rc file. If specified as \fI--norc-file\fP, no option file will be used even if one exists. .IP "--sender \fIemail-address\fP" An email address to put into the message "From" field (distinct from the "From:" field). This is useful for environments which don't honour the Errors-To field. Defaults to the value of the --errors-to option if one is set, otherwise to the value of the --from option. .IP "--subject \fIprintf-string\fP" A string to be used when constructing the Subject: of the response message. "%s" in the string will be replaced by the subject of the original message, after removal of any leading "Re:\ " or "Sv:\ " strings. The default is "Re: %s". .IP "--[no]verbose" Controls whether detailed processing messages are displayed. By default they are not. .IP "--version" Displays the programme version and exits. Don't put this into your rc file, or the autoresponder won't do anything! .IP "--work-dir \fIdirectory\fP" Specifies where temporary files should be placed; this may be important if large messages are sent to the autoresponder's address. The default value is "/tmp". .PP The conditional expressions (\fI\--ignore-from\fP, \fI\--ignore-subject\fP, and \fI\--ignore-precedence\fP) are handled with a Boolean OR operation. That is, if \fIany\fP of the patterns match, the message will be ignored and no reply will be sent. .SH "EXIT STATUS" .B autoresponder returns an exit status of 1 if there are problems with the command-line options. Otherwise, the exit status is zero indicating a successfully processed message. .SH "EXAMPLES" All of these examples are of usage in \fI.qmail\fP files, and assume that the \fIautoresponder\fP script is invoked using the following single line in the \fI.qmail\fP file: .IP \fB| /home/doe/autoresponder-script\fP .PP This is because \fI.qmail\fP files cannot contain continuation lines. Therefore, the examples show modifications to the \fIautoresponder-script\fP file, not the \fI.qmail\fP file proper. .PP If \fI/home/doe/autoresponder-script\fP contains: .PP \fB#!/bin/sh .br /home/doe/autoresponder \e --from=john.doe@nowhere.com \e --ignore-from="MAILER-DAEMON@.*" \e --ignore-header="X-Spam-Status:^yes" \e --subject="On holiday (was: %s)" \e --file=$HOME/vacation.txt\fP .IP This will cause all messages received by the account to get an response back, \fBunless\fP the incoming message came from a MAILER-DAEMON address \fBor\fP the value of the \fIX-Spam-Status\fP header field starts with the word 'yes'. The subject of the response will be altered; if the original subject was "Meeting Tuesday", the subject of the automatic response would be "On holiday (was: Meeting Tuesday)". .br \fBNote:\fP If this is the only entry in the \fI.qmail\fP file, no copy of the original message will be kept. .LP If the \fI/home/doe/autoresponder-script\fP file contains: .PP \fB#!/bin/sh .br /home/doe/autoresponder \e --from=john.doe@nowhere.com \e --ignore-from="MAILER-DAEMON@.*" \e --ignore-from="postmaster@.*" \e --ignore-subject="failed" \e --ignore-subject="not delivered" \e --file=$HOME/vacation.txt\fP .IP This is very similar to the last example, except that the generated replies with have the same subjects as the messages to which they refer, and messages coming from a couple of known delivery notification addresses will be ignored and have no reply sent to them. .LP If the \fI.qmail\fP file contains .PP \fB/home/techsupport/archive/inbound.mbox\fP .br \fB| /home/doe/autoresponder-script\fP .PP and the \fI/home/doe/autoresponder-script\fP file contains: .PP \fB#!/bin/sh .br /home/techsupport/autoresponder-script \e --file=ack.txt \e --from="Tech Support " \e --errors-to="human-response@Nowhere.Com" \e --include-original \e --work-dir=/home/techsupport/autoresponder.work\fP .IP As a complete \fI.qmail\fP file, this will save the inbound message in an mbox-formatted file, and send an automatic reply back to the sender. The text of the reply will come from the file \fIack.txt\fP, and the original message will be attached. The reply itself will not itself replyable-to; this should avoid loops when handling spam sent from a bogus address. Any errors encountered in the delivery of the reply may be sent to the 'human-response' address. Working files are created in the \fIautoresponder.work\fP subdirectory. .SH "SECURITY CONSIDERATIONS" Use of the \fI--work-dir\fP option is \fBstrongly recommended\fP. Otherwise, message files will be created in the default directory (/tmp), and sensitive information may be exposed. .PP Similarly, use of the history tracking and \fI--accept-for\fP capabilities are recommended to ward off spam. .SH "RESTRICTIONS" In the work directory, \fBautoresponder\fP will create files for the incoming message and the result of parsing it. These files may or may not be automatically cleaned up depending upon the version of the \fIMIME::Parser\fP module you have installed. Older versions will require manual cleanup; a \fIcrontab\fP entry such as the following may be appropriate: .PP \fB0 * * * * touch \fIworkdir\fP/marker && find \fIworkdir\fP/ -cmin +60 -type f | xargs rm -f \fIworkdir\fP/marker .PP This will delete on an hourly basis any work files that are more than an hour old. .SH "FILES" \fIworkdir\fP/regdata-*.data .br \fIworkdir\fP/* .br \fIdatabase-file\fP.dir, \fIdatabase-file\fP.pag .SH "BUGS" .IP "o" Options with values containing whitespace (\fIe.g.\fP, '--from "Foo Bar "' are not handled properly when read from the rc file. Make sure that there are not embedded whitespace characters in your options when you specify them in an rc file. .SH "AUTHOR" Rodent of Unusual Size .SH "SEE ALSO" Perl modules MIME::Parser, MIME::Entity, MIME::Base64, Mail::Address, Getopt::Long.