LocalDelivery.pm version 0.21 ============================= =head1 NAME Mail::LocalDelivery - Deliver mail to a local mailbox =head1 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 =head1 DESCRIPTION =head1 METHODS =head2 C<new($data, %options)> This creates a new object for delivery. The data can be in the form of an array of lines, a C<Mail::Internet> object, a C<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 C<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. =head2 C<deliver($where, ...)> You can choose to deliver the mail into a mailbox by calling the C<deliver> method; with no argument, this will look in: =over 3 =item 1 C<$ENV{MAIL}> =item 2 F</var/spool/mail/you> =item 3 F</var/mail/you> =item 4 F<~/Maildir/> =back Unix mailboxes are opened append-write, then locked F<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 "/", C<deliver> will create arbitarily deep subdirectories accordingly. Untaint your input by saying $username =~ s,/,-,g; C<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 C<deliver> is unable to write the message (eg. you're over quota), Mail::LocalDelivery will attempt delivery to the C<emergency> mailbox. If C<deliver> was called with multiple destinations, the C<emergency> action will only be taken if the message couldn't be delivered to any of the desired destinations. By default the C<emergency> mailbox is set to the system mailbox. If we were unable to save to the emergency mailbox, C<Mail::LocalDelivery> will return an empty list. =head1 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. =head1 SEE ALSO L<Mail::Internet>, L<Mail::SMTP>, L<Mail::Audit> =head1 AUTHORS Maintained by Jose Castro, C<cog@cpan.org>. This module is essentially C<Mail::Audit>'s brains, which we scooped out into a separate module since local delivery is a useful thing, and it makes C<Mail::Audit> maintainable again. So the authors of this are really the authors of C<Mail::Audit>: Simon Cozens <simon@cpan.org> and Meng Weng Wong <mengwong@pobox.com>. =head1 LICENSE The usual. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.