# 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](https://metacpan.org/pod/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](https://metacpan.org/pod/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`](https://metacpan.org/pod/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.