/ 
Sietima-1.0.3
River stage zero No dependents
/ Sietima

NAME

Sietima - minimal mailing list manager

VERSION

version 1.0.3

SYNOPSIS

use Sietima;

Sietima->new({
  return_path => 'the-list@the-domain.tld',
  subscribers => [ 'person@some.were', @etc ],
})->handle_mail_from_stdin;

DESCRIPTION

Sietima is a minimal mailing list manager written in modern Perl. It aims to be the spiritual successor of Siesta.

The base Sietima class does very little: it just puts the email message from STDIN into a new envelope using "return_path" as sender and all the "subscribers" addresses as recipients, and sends it.

Additional behaviour is provided via traits / roles. This class consumes MooX::Traits to simplify composing roles:

Sietima->with_traits(qw(AvoidDups NoMail))->new(\%args);

These are the traits provided with the default distribution:

AvoidDups

prevents the sender from receiving copies of their own messages

Debounce

avoids mail-loops using a X-Been-There header

Headers

adds List-* headers to all outgoing messages

ManualSubscription

specifies that to (un)subscribe, people should write to the list owner

NoMail

avoids sending messages to subscribers who don't want them

ReplyTo

optionally sets the Reply-To header to the mailing list address

SubjectTag

prepends a [tag] to the subject header of outgoing messages that aren't already tagged

SubscriberOnly::Drop

silently drops all messages coming from addresses not subscribed to the list

SubscriberOnly::Moderate

holds messages coming from addresses not subscribed to the list for moderation, and provides commands to manage the moderation queue

The only "configuration mechanism" currently supported is to initialise a Sietima object in your driver script, passing all the needed values to the constructor. Sietima::CmdLine is the recommended way of doing that: it adds command-line parsing capability to Sietima.

ATTRIBUTES

return_path

A Email::Address instance, coerced from string if necessary. This is the address that Sietima will send messages from.

subscribers

An array-ref of Sietima::Subscriber objects, defaults to the empty array.

Each item can be coerced from a string or a Email::Address instance, or a hashref of the form

{ address => $string, %other_attributes }

The base Sietima class only uses the address of subscribers, but some roles use the other attributes (NoMail, for example, uses the prefs attribute, and SubscriberOnly uses aliases via match)

transport

A Email::Sender::Transport instance, which will be used to send messages. If not passed in, Sietima uses Email::Sender::Simple's default_transport.

METHODS

handle_mail_from_stdin

$sietima->handle_mail_from_stdin();

This is the main entry-point when Sietima is invoked from a MTA. It will parse a Email::MIME object out of the standard input, then pass it to "handle_mail" for processing.

handle_mail

$sietima->handle_mail($email_mime);

Main driver method: converts the given email message into a list of Sietima::Message objects by calling "munge_mail", then sends each of them by calling "send_message".

subscribers_to_send_to

my $subscribers_aref = $sietima->subscribers_to_send_to($email_mime);

Returns an array-ref of Sietima::Subscriber objects that should receive copies of the given email message.

In this base class, it just returns the value of the "subscribers" attribute. Roles such as AvoidDups modify this method to exclude some subscribers.

munge_mail

my @messages = $sietima->munge_mail($email_mime);

Returns a list of Sietima::Message objects representing the messages to send to subscribers, based on the given email message.

In this base class, this method returns a single instance to send to all "subscribers_to_send_to", containing exactly the given email message.

Roles such as SubjectTag modify this method to alter the message.

send_message

$sietima->send_message($sietima_message);

Sends the given Sietima::Message object via the "transport", but only if the message's envelope specifies some recipients.

list_addresses

my $addresses_href = $sietima->list_addresses;

Returns a hashref of Sietima::HeaderURI instances (or things that can be passed to its constructor, like Email::Address, URI, or strings), that declare various addresses related to this list.

This base class declares only the "return_path", and does not use this method at all.

The Headers role uses this to populate the various List-* headers.

command_line_spec

my $app_spec_data = $sietima->command_line_spec;

Returns a hashref describing the command line processing for App::Spec. Sietima::CmdLine uses this to build the command line parser.

This base class declares a single sub-command:

send

Invokes the "handle_mail_from_stdin" method.

For example, in a .qmail file:

|/path/to/sietima send

Roles can extend this to provide additional sub-commands and options.

AUTHOR

Gianni Ceccarelli <dakkar@thenautilus.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Gianni Ceccarelli <dakkar@thenautilus.net>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.