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.

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 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.

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.