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.