path: root/maildrop/mailbot.sgml

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!-- Copyright 1998 - 2009 Double Precision, Inc.  See COPYING for -->
<!-- distribution information. -->
<refentry id="mailbot">
  <info><author><firstname>Sam</firstname><surname>Varshavchik</surname><contrib>Author</contrib></author><productname>Courier Mail Server</productname></info>

  <refmeta>
    <refentrytitle>mailbot</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class='manual'>Double Precision, Inc.</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>mailbot</refname>
    <refpurpose>A MIME-aware autoresponder utility</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis sepchar=" ">
      <command>mailbot</command>
      <arg choice="opt" rep="norepeat">options</arg>
      <arg choice="req" rep="norepeat"><replaceable>program</replaceable></arg>
      <arg rep="repeat" choice="opt">arg</arg>
    </cmdsynopsis>

    <informalexample>
      <para>In <filename>.mailfilter:</filename></para>
      <programlisting format="linespecific">
if (/^Subject: *info/)
{
     cc "| mailbot -t /usr/share/autoresponse/info -d autoresponsedb \
            -A 'From: info@domain.com' /usr/bin/sendmail -f ''"
}
</programlisting>
    </informalexample>
  </refsynopsisdiv>

  <refsect1 id="mailbot_description">
    <title>DESCRIPTION</title>


    <para><command>mailbot</command> reads an E-mail message on standard input
and creates an E-mail message replying to the original message's sender.
A
<command>program</command> is specified as an argument to
<command>mailbot</command> after all of <command>mailbot</command> options.
<command>program</command> is expected to read the
created autoreply on its standard input, and mail it.
If <command>program</command> is not specified,
<command>mailbot</command> runs '<literal>sendmail -f ""</literal>'.</para>

    <para>
<command>mailbot</command> has several options for suppressing duplicate
autoresponse messages.
If <command>mailbot</command> chooses not to send an autoresponse, it quietly
terminates without running <command>program</command>.
The autoresponse is optionally
formatted as a MIME delivery status notification.</para>

    <para>
The text of the autoresponse is specified by the <option>-t</option> or
the <option>-m</option> argument. Either one is required.
Everything else is optional.
The only exception is the <option>-T replydraft</option> option, which requires
the <option>-l</option> option instead of either <option>-t</option> or
<option>-m</option>.
The default behavior is to send an autoresponse unless the original message
has the "<literal>Precedence: junk</literal>" or the
"<literal>Precedence: bulk</literal>" header, or the
"<literal>Precedence: list</literal>" header, or the
"<literal>List-ID:</literal>" header,
or if
its MIME content type is "<literal>multipart/report</literal>"
(this is the MIME content type for delivery status notifications).
The <option>-M</option> option formats the
the autoresponse itself as a MIME delivery status notification.</para>
  </refsect1>

  <refsect1 id="mailbot_options">
    <title>OPTIONS</title>

    <variablelist>
      <varlistentry>
	<term>-A "<replaceable>header: value</replaceable>"</term>
	<listitem>
	  <para>
	    Add a header to the autoresponse. Multiple <option>-A</option>
	    options are allowed.
	    In most situations, the <option>-A</option> option must be
	    used to set the <quote>From:</quote> header in the autogenerated
	    response.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-f<replaceable>address</replaceable></term>
	<listitem>
	  <para>
Address the autoresponse to <replaceable>address</replaceable>, which must
be an
<ulink url="http://tools.ietf.org/html/rfc2822">RFC 2822</ulink>
address.
By default <command>mailbot</command> takes the autoresponse
address from the
<literal>From:</literal> (or the <literal>Reply-To:</literal>) header
in the original message.
<option>-f</option>, if present, overrides and explicitly sets the
autoresponse address.
"<replaceable>address</replaceable>" must immediately follow the
<option>-f</option> option without an intervening space
(it's a single command line argument).
An <option>-f</option> option without an <replaceable>address</replaceable>
takes the address from the <envar>SENDER</envar> environment variable.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-t <replaceable>filename</replaceable></term>
	<listitem>
	  <para>
Read text autoresponse from <replaceable>filename</replaceable>,
which must contain a plain text message in <quote>flowed-text</quote> format.
In a <quote>flowed-text</quote>-formatted message, each line that ends with
a space character indicates that the line logically flows into the next line.
This allows the message to be reformatted for any shown display width.
	  </para>

	  <note>
	    <para>
Messages in languages (see the <option>-c</option>
option) which use spaces as word delimiters must have <emphasis>two</emphasis>
spaces at the end of a flowed line. The last space on a flowed line is logically
removed, and the first space separates the
last word on the previous line from the first word on the next line. Otherwise,
the two words will not have a logical space between them if they get
repositioned as part of adjusting the message's width for display.
	    </para>

	    <para>
Messages in ideographic languages that do not use spaces as word delimiters
need only one space trailing a flowed line.</para>
	  </note>

	  <note>
	    <para>
The trailing whitespace has no visual impact when shown by software
that does not implemented flowed text format, and always displays messages
using their original width.</para>
	  </note>

	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-c <replaceable>charset</replaceable></term>
	<listitem>
	  <para>
Set the autoresponse's MIME character set to
<replaceable>charset</replaceable>.
Run <command>mailbot</command> without any arguments to see the
default character set.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-m <replaceable>filename</replaceable></term>
	<listitem>
	  <para>
	    Read a MIME autoresponse from <filename>filename</filename>.
	    This is similar to the <option>-t</option> option,
	    except that <replaceable>filename</replaceable> contains MIME headers,
	    followed by a blank line, and the corresponding
	    MIME content. The contents of <replaceable>filename</replaceable> are
	    inserted in the autoresponse without further processing.</para>

	  <para>
	    The specified file must contain the
	    <quote>Content-Type</quote> header specifying the
	    <quote>text/plain</quote> MIME type, with the
	    <quote>format=flowed</quote>,
	    <quote>delsp=yes</quote>, and the
	    <quote>charset</quote> attributes, which override the
	    <option>-c</option> parameter.
	    If the specified file has a <quote>Content-Transfer-Encoding</quote>
	    header it must be either <quote>7bit</quote> or <quote>8bit</quote>,
	    it may not be <quote>quoted-printable</quote>.
	    <command>mailbot</command> always drops any
	    existing <quote>Content-Transfer-Encoding</quote> header and
	    always adds the
	    <quote>Content-Transfer-Encoding: 8bit</quote> header, even with
	    the <option>-m</option>, since the salutation inserted into the
	    message includes the sender's name, which may contain 8-bit
	    characters. Example:
	  </para>

	  <blockquote>
	    <informalexample>
	      <programlisting>
Content-Type: text/plain; format=flowed; delsp=yes;
              charset="iso-8859-1"

Mary had a little lamb,&#32;&#32;
Its fleece was white as snow.&#32;&#32;
And everywhere Mary went,&#32;&#32;
The lamb was sure to go.</programlisting>
	    </informalexample>
	  </blockquote>

	  <note>
	    <para>
When the <option>-m</option> option is specified
<command>mailbot</command> ignores the locale's character
set and formats the autoreply according to the character set read from the
<quote>Content-Type</quote> header.</para>
	  </note>

	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-M <replaceable>address</replaceable></term>
	<listitem>
	  <para>
	    Format the autoresponse as a delivery status notification
	    (<ulink url="http://tools.ietf.org/html/rfc1894">RFC 1894</ulink>).
	    <replaceable>address</replaceable> is an
	    <ulink url="http://tools.ietf.org/html/rfc2822">RFC 2822</ulink>
	    E-mail address that generates the DSN.
	    Note that the <option>-A</option> option should still be used in
	    addition to <option>-M</option> in order to set the
	    <literal>From:</literal> header on the autoresponse.
	    <option>-M</option> sets the DSN address only.
	    The <option>-M</option> option automatically sets
	    <option>-T <literal>replydsn</literal></option>
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-R <replaceable>type</replaceable></term>
	<listitem>
	  <para>
	    Specify the feedback report type, with
	    <replaceable>type</replaceable> set to
	    <literal>abuse</literal>,
	    <literal>fraud</literal>,
	    <literal>other</literal>, or
	    <literal>virus</literal>.
	    Must be used together with <quote>-T feedback</quote> or
	    <quote>-T replyfeedback</quote>.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-T <replaceable>format</replaceable></term>
	<listitem>
	  <para>
	    Set the reply format. <replaceable>format</replaceable>
	    must be one of the following values:
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		<quote>reply</quote> - the default reply format.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<quote>replyall</quote> - like <quote>reply</quote>, except
		also puts the recipients in the original message's
		<quote>To:</quote> and <quote>Cc:</quote> headers into the
		<quote>Cc:</quote> header of the generated reply.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<quote>replydsn</quote> - like <quote>reply</quote>, except
		the message is formatted as a delivery status notification.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<quote>replydraft</quote> - like <quote>reply</quote>, with
		the text of the autoresponse coming from a maildir specified
		by the <option>-l</option> option. See <quote>Autoreplies
		  from a maildir folder</quote>, below.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<quote>forward</quote> - attach the original message as
		forwarded text.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<quote>forwardatt</quote> - attach the original message as
		a forwarded message attachment.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote>feedback</quote> - generate an Email Feedback Report
		message (see <ulink url="http://tools.ietf.org/html/rfc5965">RFC
		  5965</ulink>). The <quote>-R</quote> option is required when
		this is specified.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<quote>replyfeedback</quote> - like <quote>feedback</quote>, but
		also adds a <quote>To:</quote> header, addressed to the original
		message's sender.
	      </para>
	    </listitem>
	  </itemizedlist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-N</term>

	<listitem>
	  <para>
	    Do not quote the contents of the original message in the message
	    created by
	    <quote><literal>reply</literal></quote>,
	    <quote><literal>replyall</literal></quote>,
	    <quote><literal>replydsn</literal></quote>,
	    <quote><literal>feedback</literal></quote>, and
	    <quote><literal>replyfeedback</literal></quote> options.
	  </para>

	  <note>
	    <para>
	      The original message gets quoted, in the absence of this option,
	      only if the original message was formatted as plain text.
	      <command>mailbot</command> is unable to quote an original
	      message which was formatted as <acronym>HTML</acronym>, or any
	      other non-plaintext format.
	    </para>
	  </note>

	  <note>
	    <para>
	      For <quote><literal>replydsn</literal></quote>,
	      <quote><literal>feedback</literal></quote>, and
	      <quote><literal>replyfeedback</literal></quote> options,
	      the convention is to attach the original message, or only its
	      headers, separately; so this option should always be specified
	      for these three reply formats.
	    </para>
	  </note>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-a</term>
	<listitem>
	  <para>
	    Attach the entire message, for
	    <quote><literal>replydsn</literal></quote>,
	    <quote><literal>feedback</literal></quote>, and
	    <quote><literal>replyfeedback</literal></quote>, instead of only its
	    headers.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-e</term>
	<listitem>
	  <para>
	    Generate a reply (<quote>reply</quote>-formats) to the
	    address listed in any <quote>Errors-To</quote> or
	    <quote>Return-Path</quote> header, if present, instead of the
	    <quote>From</quote> header.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-S <quote>salutation</quote></term>
	<listitem>
	  <para>
	    Use the given <replaceable>salutation</replaceable>
	    in the <quote>reply</quote>.
	    The default value is <quote>%F writes:</quote>.
	    The following substitutions are recognized in the salutation
	    string:
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		<literal>%%</literal> - an explicit <literal>%</literal>
		character.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>%n</literal> - a newline character.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>%C</literal> - the
		<quote>X-Newsgroup:</quote> header from the original message.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>%N</literal> - the <quote>Newsgroups:</quote>
		header from the original message.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>%i</literal> - the <quote>Message-ID:</quote>
		header from the original message.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>%f</literal> - the original message's sender's address.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>%F</literal> - the original message's sender's name.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>%S</literal> - the
		<quote>Subject:</quote> header from the original message
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>%d</literal> - the original message's date, in the
		local timezone.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>%{<replaceable>...</replaceable>}d</literal>
		- use <function>strftime</function>() to format the original
		message's date.
	        A plain <literal>%d</literal> is equivalent to
		<literal>%{%a, %d %b %Y %H:%M:%S %z}d</literal>.
	      </para>
	    </listitem>
	  </itemizedlist>

	  <para>
	    All other characters in the salutation string are left as is.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-F <quote>marker</quote></term>

	<listitem>
	  <para>
	    When generating a <literal>forward</literal>, use the
	    <replaceable>marker</replaceable> to separate the forwarded
	    message from the autoreply text, instead of the default
	    <quote>--- Forwarded message ---</quote>
	  </para>
	  </listitem>
      </varlistentry>

      <varlistentry>
	<term>-r <replaceable>addrlist</replaceable></term>
	<listitem>
	  <para>
<replaceable>addrlist</replaceable> is a comma-separated list of
<ulink url="http://tools.ietf.org/html/rfc2822">RFC 2822</ulink>
E-mail addresses.
<command>mailbot</command> sends an autoresponse only if
the original message has at least one of the specified addresses in any
<literal>To:</literal> or <literal>Cc:</literal> header.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-d <replaceable>filename</replaceable></term>
	<listitem>
	  <para>
Create a small database, <replaceable>filename</replaceable>,
that keeps track of senders' E-mail addresses,
and prevent duplicate autoresponses going to the same address
(suppress autoresponses going back to the same senders, for subsequent
received messages).
The <option>-d</option> option is only available if
<command>maildrop</command> has GDBM/DB extensions enabled.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-D <replaceable>x</replaceable></term><listitem>
	  <para>
Do not send duplicate autoresponses (see the
<option>-d</option> option) for at least
<replaceable>x</replaceable> days (default: 1 day). The
<option>-d</option> option creates a database of E-mail addresses and
the times an
autoresponse was last mailed to them. Another autoresponse to the same
address will not be mailed until at least the amount of time specified by
the <option>-D</option> option has elapsed.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-s "<replaceable>subject</replaceable>"</term>
	<listitem>
	  <para>
Set the <literal>Subject:</literal> header on the autoresponse to
<replaceable>subject</replaceable>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-n</term>
	<listitem>
	  <para>
	    Show the resulting message, do not send it. Used for debugging
	    purposes.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--feedback-original-envelope-id&nbsp;<replaceable>"&lt;envelopeid&gt;"</replaceable>,
	  --feedback-original-mail-from&nbsp;<replaceable>"&lt;mailfrom&gt;"</replaceable>,
	  --feedback-reporting-mta&nbsp;"<replaceable>dns;&nbsp;hostname"</replaceable>,
	  --feedback-source-ip&nbsp;<replaceable>aaa.bbb.ccc.ddd</replaceable>,
	  --feedback-incidents&nbsp;<replaceable>n</replaceable>,
	  --feedback-authentication-results&nbsp;<replaceable>"results"</replaceable>,
	  --feedback-original-rcpt-to&nbsp;<replaceable>"&lt;rcptto&gt;"</replaceable>,
	  --feedback-reported-domain&nbsp;<replaceable>example.com</replaceable></term>

	<listitem>
	  <para>
	    Optional parameters to include in the feedback report generated by
	    <quote>feedback</quote> and <quote>replyfeedback</quote>.
	    <command>mailbot</command> always adds
	    <quote>Arrival-Date</quote> with the current time, as well as
	    <quote>Version</quote> and <quote>User-Agent</quote>.
	  </para>

	  <para>
	    <quote>--feedback-authentication-results</quote>,
	    <quote>--feedback-original-rcpt-to</quote> and
	    <quote>--feedback-reported-domain</quote> may be specified more
	    than once.
	  </para>

	  <para>
	    Where appropriate, UTF-8 encoding should be used for non-ASCII
	    characters.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-l <replaceable>maildir</replaceable></term>

	<listitem>
	  <para>
	    Specifies the maildir for the <quote>-T replydraft</quote>
	    option. See <quote>Autoreplies
	      from a maildir folder</quote>, below.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <refsect2 id="mailbot_autoreplies_from_a_maildir_folder">
      <title>Autoreplies from a maildir folder</title>

      <para>In <filename>.mailfilter:</filename></para>

      <blockquote>
	<informalexample>
	  <programlisting>
cc "| mailbot -T replydraft -l './Maildir/.Vacation' \
        -d autoresponsedb \
        -A 'From: info@domain.com' /usr/bin/sendmail -f ''"
to "./Maildir"</programlisting>
	</informalexample>
      </blockquote>

      <para>
	The <option>-T replydraft</option> reply format takes the content of
	the autoresponse from the most recent message in a maildir.
	The <option>-l</option> option specifies the maildir. The above
	example takes the message from <literal>$HOME/Maildir/.Drafts</literal>
	which should be a maildir (with the usual <filename>cur</filename>,
	<filename>new</filename>, and <filename>tmp</filename> subdirectories).
	It would typically get created by Courier-IMAP as a folder named
	<quote>Vacation</quote>.
      </para>

      <para>
	This makes it possible to install autoreplies via an IMAP client by
	creating a folder named <quote>Vacation</quote>, and copying a message
	into it. The contents of the message become the autoresponse.
      </para>

      <para>
	If the named maildir does not exist, or is empty,
	<command>mailbot</command> does nothing. If the named maildir has
	more than one message, the most recent message gets used.
      </para>

      <para>
	The above example uses additional <command>mailbot</command> options
	to suppress duplicate autoresponses, and to set the <quote>From:</quote>
	header on the autoresponse.
      </para>
    </refsect2>

  </refsect1>

  <refsect1 id="mailbot_see_also">
    <title>SEE ALSO</title>

    <para>
<ulink url="maildrop.html"><citerefentry><refentrytitle>maildrop</refentrytitle><manvolnum>1</manvolnum></citerefentry></ulink>,
<ulink url="reformail.html"><citerefentry><refentrytitle>reformail</refentrytitle><manvolnum>1</manvolnum></citerefentry></ulink>,
<ulink url="reformime.html"><citerefentry><refentrytitle>reformime</refentrytitle><manvolnum>1</manvolnum></citerefentry></ulink>.
</para>
  </refsect1>
</refentry>