**********************
Response documentation
**********************

*Automatic / Out of Office / Vacation E-Mail Responder*

    Author:  John Feuerstein <[email protected]>

    License: GPLv3

    Project URL: http://feurix.org/projects/response/

    Development URL: https://labs.feurix.org/mail/response/


Feel free to contribute! Clone the repo, send me pull requests, patches, bugs
reports, suggestions, critics... :)


Description of Response
-----------------------

Response is a suite of tools and daemons used to implement automatic e-mail
responses, also called "Out of Office" or "Vacation" messages.

It tries hard to do that "the correct way", ie. not responding to e-mails that
should not be responded to. All of the validation code can easily be modified
to suite your needs, however we try hard to ship sane defaults.

It supports response limits per recipient in a given time and comes with a
default setting of the recommended "one autoresponse per recipient in 7 days".

Response was written to get rid of some common headaches to all mail
administrators caused by poorly written autoresponse-scripts.

In fact, most of current response implementations out there are a pain in the
ass. They cause a lot of so called backscatter, auto-blacklisting of the whole
mailserver, inconvenience for recipients of unlimited multiple responses, lack
support for virtual users, lack in scalability, and probably more...


RDBMS driven Backend and Virtual Users
--------------------------------------

Response has scalability in mind. Using .vacation files or local MDA filters
and scripts is not applicable.

Response uses a RDBMS as it's backend for response-address-configurations and
response-recordings. You are free to use custom SQL queries for every
operation, even though we ship usable defaults to get you started easily.

Currently, MySQL is the only supported database backend. PostgreSQL support is
already prepared and quite easy to implement. Feel free to contribute! :-)
SQLite lacks adequate locking mechanisms to support the needed concurrency.

The database adapters use connection pooling and you can easily configure the
error behaviour, ie. ask the delivering MTA to try again later (softfail), to
bounce the message and even inform the sender (not suggested, hardfail) or to
always fake success (failsafe).


Design
------

Response works only in combination with an intelligent MTA like Postfix. It
has no own mail queue (hence, LMTP) and relies on the delivering MTA to
silently copy a given mail and hand it over. It has 3 components:

    (1) A LMTP-daemon to handle incoming messages, validate sender, recipient,
        and headers. The message body is dropped. If the validation is
        successful, a new response record is recorded. If there already was
        a matching one (sender<->recipient), the given record's last hit
        timestamp is updated. You may run multiple instances on multiple
        mailservers or point multiple mailservers to one instance. The first
        step of recipient validation (autoresponse enabled, configured?) may
        be done directly by the MTA which results in very good performance.

    (2) The Notifier. This component may run on the same machine or any other.
        It can use any custom SMTP relay to send the responses. To keep it as
        flexible as possible it is not designed as a long running process.
        The suggested way to run it is via Cron. Messages are assembled using
        per user data from the configuration in the backend. This means custom
        subjects and custom bodies per response-sender are possible. Avoiding
        any loops or other unwanted reaction on the sent responses is taken
        special care of. Response limiting happens here, based on last sent
        and last hit timestamps of each record in the backend.

    (3) The Cleanup component. It may run on any machine that can access the
        backend. In fact, it is not necessarily needed and completely
        optional. Depending on your userbase and activity it is recommended to
        keep your backend database as small and fast as possible, though. It
        takes care of disabling expired autoresponse configurations and
        removing obsolete response records. All cleanup operations may be run
        separately (or all at once), to give you the most flexibility
        available. Again, use Cron to schedule the cleanup operations.

The components are described in more detail in the following sections.


Response LMTP Daemon
--------------------

The main autoresponse validation and recording component (response-lmtpd) is
implemented as a LMTP daemon doing message validation, queueing new pending
response records and recording the arrival of the last valid message to a
configured autoresponse address. SMTP is not applicable here because we don't
want to implement a (possibly bad performing) queue. The mail queues and queue
schedulers of modern MTAs are very good, so let's make use of them.

Logging can go to stderr or directly to syslog. You can freely configure the
syslog facility. If you run response-lmtpd daemonized, logging always goes to
syslog.

The LMTP daemon should be used as a final secondary transport by your MTA.

This way, weird autoresponse subdomains or extraneous autoresponse address
formats (at least as seen by your users or any outsider) are NOT required.

If your MTA is configured correctly (see examples) your recipient (no matter
if local or virtual) will get the e-mail as usual and the autoresponse will
just work(tm).

If you know your MTA and can work with transport tables you get great
flexibility. This is in contrast to all poorly designed autoresponse scripts
and sieve filters, executing once per message, being slow, inflexible, bound
to one mailserver, ...


Response Notify
---------------

The autoresponse-sending component (response-notify) is completely independent
and can run on the same or a different machine. It can send autoresponses
using any SMTP-relay you configure, using plain SMTP, STARTTLS, and SMTP-AUTH.

Response-notify is currently invoked by Cron and hence can run in custom
intervals. However you want it.


Response Cleanup
----------------

The cleanup component disables expired autoresponse configs (to get around
lazy users forgetting about their responder or to implement a "expire" feature
in the configuration front-end -- this is up to you).

In addition, it can remove stale response records for already disabled
response configs or help you to get rid of inactive response records.


Security
--------

Each component may run as a different, isolated system user. If you prepare
the needed environment, they may even run chrooted. No local file access,
except for the configuration, libraries, and the pidfile is needed. Securing
your RDBMS is a chapter on its own. To keep it short, you may use different
RDBMS-users for each component, restricting their access to the minimum needed
to perform the configured queries.


Final words
-----------

Response is scalable, you can use it on one mailserver or a whole
infrastructure.

Configuring autoresponses is as easy as doing a single SQL query. This way you
can easily allow your users to configure them using any Webmail application.
(See the examples for a simple Roundcube plugin)

Finally, if you have any comments, suggestions, critics, new validation
filters, better SQL, whatever -- feel free to contribute. Thanks! :-)


.. vim: tw=78