Configuring the Queues

With the mail queue being the heart of an MTA, the queue section of slimta.conf is both important and highly customizable. It also introduces the possibility of using the slimta-worker executable for some queue types. In the queue section, each key provides an arbitrary, free-form name for the queue. The sub-section for each key has two required settings:

  • type: String, required

    Defines the type of queue. A known type must be given or an error will be thrown. The other keys in this mapping depend on the value of type.

  • relay: String, required

    Delivery attempts of messages in the queue are passed to this relay. The value is a name, which must correspond to a key in the top-level relay section.

  • bounce_queue: String

    Often when mail is to be relayed locally, the relay is incapable of delivering bounce messages to arbitrary sender addresses hosted elsewhere. You may also want to apply different retry behavior to bounce messages. This option allows you to specify the name of another queue in the top-level queue section, which will be used to deliver bounce messages instead of the current queue.

Queue Policy Settings

On entry into the queue, there are several Policy Implementation that can be applied to a message. To configure them, there is an additional, optional key available in a queue sub-section:

  • policies: List

    Each entry in this list is a dictionary with a type field. Check out the Policy Implementation page for more information about each type:

    • add_date_header: Adds the Date: header to the message.

    • add_message_id_header: Adds the Message-Id: header to the message.

    • add_received_header: Adds a Received: header to the message.

    • recipient_split: Forks the message so that for each recipient there is a deep copy of the original message.

    • recipient_domain_split: Forks the message so that for each unique domain in the message recipients there is a deep copy of the original message with the recipients for that domain.

    • forward: Rewrites recipients using regular expressions. Along with the type key, there is a mapping key which is a dictionary of replacement rules where each key is a regular expression pattern and the value is string to replace the pattern match with.

    • spamassassin: Queries a SpamAssassin server to check if the message is considered spam, adding headers to the message with the results.

Delivery Retry Behavior

Additionally, every queue type (except for "custom" and "proxy") honors the ability to configure message retrying with the following configuration settings:

  • retry: Dictionary

    If this dictionary is not given, messages are never retried. This dictionary has two keys, delay and maximum:

    • delay: String

      Defines an mathematic expression whose result is used as the number of seconds to delay between each delivery attempt of a message. The string allows arithmetic operators and the use of any functions in the math module (without the math. prefix). The variable x may be used in the expression, and will be replaced with the number of delivery attempts the message has undergone.

      For example, passing the string "300*x" will start the delay at five minutes, and increase the delay by an additional five minutes for each attempt on the message.

      The default value of this setting is "300", which results in messages being retried every five minutes until the maximum number of attempts has been reached.

    • maximum: Integer

      Defines the maximum number of retries before a message is failed. If this value is not given, messages are never retried.

memory Queues

With this queue type, all queued messages and their metadata reside in memory. While this is fast and easy to setup, it is not safe for production usage, and can easily result in loss of mail. The "memory" queue type does not have any additional settings.

disk Queues

With this queue type, messages and their metadata are spooled to disk before acceptance. This queue type requires three directories, which are configured with the following keys:

  • tmp_dir: String

    This directory is used as scratch space so that files can be created and written before being moved to their final destination. This allows for the use of the atomic os.rename() operation, to help prevent data corruption. By default, the OS-specific temporary directory is used.

  • envelope_dir: String, required

    In this directory, the message contents and envelope information are written to files that use the .env suffix in a Python pickle format.

  • meta_dir: String, required

    In this directory, the message metadata is kept in files that end in .meta. This information is primarily related to the delivery of the message, including how many attempts it has undergone, and is kept separately so that it can be written to often.

redis Queues

With this queue type, messages and their metadata are stored as a hash in a local or remote redis instance. Additionally, a queue is maintained in redis of pending new message IDs, meaning this mechanism can receive and deliver messages across processes. This queue type is configured with the following keys:

  • host: String

    This is the hostname of the redis instance to connect to and use as queue storage. By default, localhost is used.

  • port: Integer

    This is the port to connect to on the redis instance. By default, 6379 is used.

  • db: Integer

    Upon connection, this is the database number to SELECT before doing anything else. By default, 0 is used.

  • password: String

    If given, the AUTH command is called with this string before doing anything else with the connection.

  • prefix: String

    This string is prefixed to every key created by the redis storage engine. This can be used to isolate keys from others in the system, to allow for multiple redis storage engines to run in the same database, or just to make keys more recognizable. By default, slimta: is used.

aws Queues

This queue type stores messages and their metadata in AWS services. The boto library must be installed from PyPI to use this queue type. It takes the following keys:

  • access_key_id: String

    Your AWS Access Key ID. If this is not given, the boto library attempts to fetch this value from environment variables.

  • secret_access_key: String

    Your AWS Secret Access Key. If this is not given, the boto library attempts to fetch this value from environment variables.

  • bucket_name: String, required

    The S3 bucket name used to create storage objects containing the Envelope and queue metadata.

  • queue_name: String

    The SQS queue name used by the storage engine. If this value is not given, SQS will not be used.

  • queue_region: String

    The SQS queue region. By default, us-west-2 is used.

proxy Queues

The "proxy" queue type is not a queue at all, but rather a method of bypassing the queue step and immediately attempting message delivery. If delivery fails, the client gets immediate feedback from the edge service. There are no additional configuration settings for this queue type.

custom Queues

Only one additional key is required by the "custom" queue type:

  • factory: String, required

    This is a string of the form package.module:symbol. The package and module portion are imported with importlib.import_module(), and then the symbol is fetched from the loaded module with getattr().

    The result of loading the symbol must be a function that takes two arguments, the options object (that contains the type, relay, and factory keys as well as any others as necessary) and the Relay object that the queue should use for message delivery:

    def queue_factory(options, relay):
    if 'foo' in options:
        return FooQueue(options.stuff, relay)
    else:
        return BarQueue(options.baz, relay)