root/doc/modules.txt

= Project Lancelot Modules =

This is a brief overview of the various processing modules that can be
used in Project Lancelot workflows.

At this stage, the only workflow that makes sense is the '''submit'''
workflow, and a suitable definition would be
{{{
 mail.workflow.submit = policy_addresses policy_mime list_headers post_message
}}}

== Module list_headers ==

=== Description ===

This module performs various header manipulations:

 * Insertion of RFC2919 and RFC2369 headers
 * Subject-line tagging
 * ''Reply-To:'' munging

=== Configuration Parameters ===

 * '''mail.forcereplyto''' (boolean): If true, and if
   '''mail.replyto''' is set, adds a ''Reply-To:'' header to the
   message using the content of '''mail.replyto'''. Any previous
   ''Reply-To:'' header is overwritten. (''Note:'' The issue of
   whether using this is actually a good idea is highly contentious.)
   (Default: '''false''')

 * '''mail.listheaders''' (boolean): If true, RFC2369 headers
   (''List-Post'', ''List-Subscribe'', and friends) will be generated
   for the list. (Default: '''true''')

 * '''mail.listid''' (string): If set, this will be used as the ''complete''
   RFC2919 ''List-ID:'' header, i.e., it should include the angle brackets
   and a comment (if desired). If not set, the ''List-ID:'' header will be
   derived from '''list.address''' by replacing the ''@'' in that
   address by ''.list-id.''. (''Note:'' There is no way of not generating
   a ''List-ID'' header.) (Default: unset)

 * '''mail.replyto''' (string): If set, this string will be used as
   the value of a ''Reply-To:'' header if the message does not already
   contain one. (Default: unset)

 * '''mail.subjecttag''' (string): If set, this string will be
   inserted at the beginning of a message's ''Subject:'' header if it
   is not already present. (A possibly empty sequence of ''Re:'' tags
   and spaces in front of the subject tag will be ignored, to keep the
   header from growing without bounds.) (Default: unset)

== Module policy_addresses ==

=== Description ===

This module can check whether the list's submission address shows up
in the current message's ''To:'' or ''Cc:'' headers, and reject the
message otherwise.

It can also check whether the sender of the current message is a subscriber
to the list, and set the '''from_subscriber''' flag on the message if
this is the case.

=== Configuration Parameters ===

 * '''mail.policy.explicitaddress''' (boolean): If true, the list's
   submission address (see '''list.address''') must occur in
   the ''To:'' or ''Cc:'' headers for the message to be considered for
   further processing, otherwise the message is bounced using the
   '''policy-addresses-explicit''' template. (Default: '''true''')

 * '''mail.policy.subscribersonly''' (boolean): Determines whether
   message senders should be tested for subscribership. If this is set
   and the message sender is not a subscriber, set the
   '''nonsubscriber''' flag on the message. (Default: '''true''')

== Module policy_mime ==

=== Description ===

This module checks the MIME type of a message and possibly its
subparts and does the following:

 * Messages of content type ''text/plain'' are accepted for further processing.
 * Messages of content type ''multipart/alternative'' are accepted for
   further processing in the following cases:
   * They contain exactly one subpart, which is of type ''text/plain''.
     (This part will be coerced to be the main body before continuing.)
   * They contain exactly two subparts, one of which is of type ''text/plain''
     and the other is of type ''text/html''. (The ''text/html'' part will
     be removed, and the ''text/plain'' part will be coerced to be the
     main message body.)
   All other ''multipart/alternative'' messages are either dropped (if
   the message contains two subparts or if the sender is not a list
   subscriber) or bounced back to the sender using the '''policy-mime'''
   template.
 * Messages of content type ''multipart/mixed'' are accepted for further
   processing if they contain exactly one subpart and that subpart is
   of type ''text/plain''. (This subpart will be made the main body as
   above.)
 * All other messages are dropped (if the sender is not a list subscriber)
   or bounced back to the sender using the '''policy-mime''' template.

== Module post_message ==

=== Description ===

This module posts the current message to the list subscribers using SMTP to
a designated server.

It performs the following operations before actually posting the message:

 * The message is given a unique message number if it does not already
   have one (e.g., because it was archived).
 * A ''Precedence: bulk'' header is added.
 * An ''X-Software:'' header is added to show off the Project Lancelot
   version number.
 * An ''X-Loop:'' header is added to avoid creating mail loops.
 * Any ''Return-Path:'' and ''Delivered-To:'' headers are removed from
   the message.

=== Configuration Parameters ===

 * '''smtp.debug''' (boolean): If true, the SMTP protocol dialogue will be
   echoed on standard error. This only makes sense when debugging.

 * '''smtp.maxrecipients''' (integer): The maximum number of recipient
   addresses passed to the SMTP server during a single SMTP message
   submission. (Default: '''100''')

 * '''smtp.port''' (string): The port number used by the SMTP server
   (Default: '''25''')

 * '''smtp.server''' (string): The name or IP address of the SMTP server.
   (Default: '''localhost''')

 * '''smtp.timeout''' (string): The SMTP timeout (in seconds). (Default: 120)