NAME

Mail::Dir - Compliant Maildir and Maildir++ delivery mechanism

SYNOPSIS

use Mail::Dir;

my $maildir = Mail::Dir->open("$ENV{'HOME'}/Maildir");

$maildir->deliver('somefile.msg');

#
# Create a new Maildir++ mailbox with sub-mailboxes
#
my $maildirPP = Mail::Dir->open("$ENV{'HOME'}/newmaildir",
    'maildir++' => 1,
    'create'    => 1
);

$maildirPP->create_mailbox('INBOX.foo');
$maildirPP->create_mailbox('INBOX.foo.bar');
$maildirPP->select_mailbox('INBOX.foo.bar');

$maildirPP->deliver(\*STDIN);

DESCRIPTION

Mail::Dir provides a straightforward mechanism for delivering mail messages to a Maildir or Maildir++ mailbox.

OPENING OR CREATING A MAILBOX

• Mail::Dir->open(_$dir_, _%opts_)

  Open or create a mailbox, in a manner dependent on the flags specified in %opts, and returns an object representing the Maildir structure.

  Recognized option flags are:

  • create

    When specified, create a Maildir inbox at $dir if one does not already exist.

  • maildir++

    When specified, enable management and usage of Maildir++ sub-mailboxes.

MANIPULATING MAILBOXES

The following methods require Maildir++ extensions to be enabled.

• $maildir->select_mailbox(_$mailbox_)

  Change the current mailbox to which mail is delivered, to $mailbox.

• $maildir->mailbox()

  Returns the name of the currently selected mailbox.

• $maildir->mailbox_exists(_$mailbox_)

  Returns true if $mailbox exists.

• $maildir->create_mailbox(_$mailbox_)

  Create the new $mailbox if it does not already exist. Will throw an error if the parent mailbox does not already exist.

DELIVERING MESSAGES

• $maildir->deliver(_$from_)

  Deliver a piece of mail from the source indicated by $from. The following types of values can be specified in $from:

  • A CODE reference

    When passed a CODE reference, the subroutine specified in $from is called, with a file handle passed that the subroutine may write mail data to.

  • A file handle

    The file handle passed in $from is read until end-of-file condition is reached, and spooled to a new message in the current mailbox.

  • A filename

    The message at the filename indicated by $from is spooled into the current mailbox.

RETRIEVING MESSAGES

• $maildir->messages(_%opts_)

  Return a list of Mail::Dir::Message references containing mail messages as selected by the criteria specified in %opts. Options include:

  • tmp, new, cur

    When any of these are set to 1, messages in those queues are processed.

  • filter

    A subroutine can be passed via CODE reference which filters for messages that are desired. Each Mail::Dir::Message object is passed to the subroutine as its sole argument, and is kept if the subroutine returns 1.

PURGING EXPIRED MESSAGES

• $maildir->purge()

  Purge all messages in the tmp queue that have not been accessed for the past 36 hours.

SEE ALSO

• Mail::Dir::Message - Manipulate messages in a Maildir queue

CONTRIBUTORS

• Nova Patch <patch@cpan.org>
• Aristotle Pagaltzis <pagaltzis@gmx.de>

AUTHOR

Alexandra Hrefna Hilmisdóttir <xan@cpan.org>

COPYRIGHT

Copyright (c) 2016, cPanel, Inc. Distributed under the terms of the MIT license. See the LICENSE file for further details.