Response documentation

Automatic / Out of Office / Vacation E-Mail Responder

Author: John Feuerstein <john@feurix.com>

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! :-)