SYNOPSIS

use Mail::LocalDelivery;
my $x = new Mail::LocalDelivery(\@some_text);
$x->deliver(); # Append to /var/spool/mail/you
$x->deliver("/home/simon/mail/test") # Deliver to Unix mailbox
$x->deliver("/home/simon/mail/test/") # Deliver to maildir

DESCRIPTION

METHODS

new($data, %options)

This creates a new object for delivery. The data can be in the form of an array of lines, a Mail::Internet object, a MIME::Entity object or a filehandle.

As for options, if you don't want the "new/cur/tmp" structure of a classical maildir, set the one_for_all option, and you'll still get the unique filenames.

new ($data, one_for_all=>1);

If you want "%" signs in delivery addresses to be expanded according to strftime(3), you can turn on the interpolate_strftime option:

new ($data, interpolate_strftime =>1);

"interpolate_strftime" is not enabled by default for two reasons: backward compatibility (though nobody I know has a % in any mail folder name) and username interpolation: many people like to save messages by their correspondent's username, and that username may contain a % sign. If you are one of these people, you should

$username =~ s/%/%%/g;

You can also supply an "emergency" option to determine where mail goes in the worst case scenario.

deliver($where, ...)

You can choose to deliver the mail into a mailbox by calling the deliver method; with no argument, this will look in:

1. $ENV{MAIL}

2. /var/spool/mail/you

3. /var/mail/you

4. ~/Maildir/

Unix mailboxes are opened append-write, then locked LOCK_EX, the mail written and then the mailbox unlocked and closed. If Mail::LocalDelivery sees that you have a maildir style system, where the argument is a directory, it'll deliver in maildir style. If the path you specify does not exist, Mail::LocalDelivery will assume mbox, unless it ends in /, which means maildir.

If multiple maildirs are given, Mail::LocalDelivery will use hardlinks to deliver to them, so that multiple hardlinks point to the same underlying file. (If the maildirs turn out to be on multiple filesystems, you get multiple files.)

If your arguments contain "/", deliver will create arbitarily deep subdirectories accordingly. Untaint your input by saying

$username =~ s,/,-,g;

deliver will return the filename(s) that it saved to.

my  @pathnames = deliver({noexit=>1}, file1, file2, ... );
my ($pathname) = deliver({noexit=>1}, file1);

If for any reason deliver is unable to write the message (eg. you're over quota), Mail::LocalDelivery will attempt delivery to the emergency mailbox. If deliver was called with multiple destinations, the emergency action will only be taken if the message couldn't be delivered to any of the desired destinations. By default the emergency mailbox is set to the system mailbox. If we were unable to save to the emergency mailbox, Mail::LocalDelivery will return an empty list.

LICENSE

The usual. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

CAVEATS

If your mailbox file in /var/spool/mail/ doesn't already exist, you may need to use your standard system MDA to create it. After it's been created, Mail::LocalDelivery should be able to append to it. Mail::LocalDelivery may not be able to create /var/spool/mail because programs run from .forward don't inherit the special permissions needed to create files in that directory.

AUTHORS

Maintained by Jose Castro, cog@cpan.org.

This module is essentially Mail::Audit's brains, which we scooped out into a separate module since local delivery is a useful thing, and it makes Mail::Audit maintainable again.

So the authors of this are really the authors of Mail::Audit: Simon Cozens <simon@cpan.org> and Meng Weng Wong <mengwong@pobox.com>.

SEE ALSO

Mail::Internet, Mail::SMTP, Mail::Audit