{
    "mode": "perldoc",
    "parameter": "Mail::Box::Maildir",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3ABox%3A%3AMaildir/json",
    "generated": "2026-06-15T13:52:35Z",
    "synopsis": "use Mail::Box::Maildir;\nmy $folder = new Mail::Box::Maildir folder => $ENV{MAIL}, ...;",
    "sections": {
        "NAME": {
            "content": "Mail::Box::Maildir - handle Maildir folders\n",
            "subsections": []
        },
        "INHERITANCE": {
            "content": "Mail::Box::Maildir\nis a Mail::Box::Dir\nis a Mail::Box\nis a Mail::Reporter\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Mail::Box::Maildir;\nmy $folder = new Mail::Box::Maildir folder => $ENV{MAIL}, ...;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This documentation describes how Maildir mailboxes work, and what you can do with the Maildir\nfolder object \"Mail::Box::Maildir\".\n\nMaildir is not supported for Windows, because it create filenames which are not accepted by the\nWindows system.\n\nExtends \"DESCRIPTION\" in Mail::Box::Dir.\n",
            "subsections": []
        },
        "OVERLOADED": {
            "content": "Extends \"OVERLOADED\" in Mail::Box::Dir.\n\noverload: \"\"\nInherited, see \"OVERLOADED\" in Mail::Box\n\noverload: @{}\nInherited, see \"OVERLOADED\" in Mail::Box\n\noverload: cmp\nInherited, see \"OVERLOADED\" in Mail::Box\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Extends \"METHODS\" in Mail::Box::Dir.\n",
            "subsections": [
                {
                    "name": "Constructors",
                    "content": "Extends \"Constructors\" in Mail::Box::Dir.\n\nMail::Box::Maildir->new(%options)\n-Option           --Defined in     --Default\nacceptnew                          <false>\naccess             Mail::Box        'r'\nbodydelayedtype  Mail::Box        Mail::Message::Body::Delayed\nbodytype          Mail::Box        Mail::Message::Body::Lines\ncoerceoptions     Mail::Box        []\ncreate             Mail::Box        <false>\ndirectory          Mail::Box::Dir   <derived from folder name>\nextract            Mail::Box        10240\nfieldtype         Mail::Box        undef\nfixheaders        Mail::Box        <false>\nfolder             Mail::Box        $ENV{MAIL}\nfolderdir          Mail::Box        $ENV{HOME}/.maildir\nheaddelayedtype  Mail::Box        Mail::Message::Head::Delayed\nheadtype          Mail::Box        Mail::Message::Head::Complete\nkeepdups          Mail::Box        <false>\nlockfile          Mail::Box        <not used>\nlocktimeout       Mail::Box        <not used>\nlocktype          Mail::Box        'NONE' (constant)\nlockwait          Mail::Box        <not used>\nlocker             Mail::Box        undef\nlog                Mail::Reporter   'WARNINGS'\nmanager            Mail::Box        undef\nmessagetype       Mail::Box        <folder-class>::Message\nmultiparttype     Mail::Box        Mail::Message::Body::Multipart\nremovewhenempty  Mail::Box        <true>\nsaveonexit       Mail::Box        <true>\ntrace              Mail::Reporter   'WARNINGS'\ntrusted            Mail::Box        <depends on folder location>\n\nacceptnew => BOOLEAN\nWhen the folder is open, some messages may be stored in the \"new\" sub-directory. By\ndefault, these messages are immediately moved to the \"cur\" directory when the folder is\nopened. Otherwise, you have to call acceptMessages() or\nMail::Box::Maildir::Message::accept().\n\naccess => MODE\nbodydelayedtype => CLASS\nbodytype => CLASS|CODE\ncoerceoptions => ARRAY\ncreate => BOOLEAN\ndirectory => DIRECTORY\nextract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'\nfieldtype => CLASS\nfixheaders => BOOLEAN\nfolder => FOLDERNAME\nfolderdir => DIRECTORY\nheaddelayedtype => CLASS\nheadtype => CLASS\nkeepdups => BOOLEAN\nlockfile => FILENAME\nlocktimeout => SECONDS\nlocktype => CLASS|STRING|ARRAY\nlockwait => SECONDS\nlocker => OBJECT\nlog => LEVEL\nmanager => MANAGER\nmessagetype => CLASS\nmultiparttype => CLASS\nremovewhenempty => BOOLEAN\nsaveonexit => BOOLEAN\ntrace => LEVEL\ntrusted => BOOLEAN\n"
                },
                {
                    "name": "The folder",
                    "content": "Extends \"The folder\" in Mail::Box::Dir.\n\n$obj->addMessage($message, %options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->addMessages(@messages)\nInherited, see \"The folder\" in Mail::Box\n\nMail::Box::Maildir->appendMessages(%options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->close(%options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->copyTo($folder, %options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->delete(%options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->directory()\nInherited, see \"The folder\" in Mail::Box::Dir\n\n$obj->folderdir( [$directory] )\nInherited, see \"The folder\" in Mail::Box\n\n$obj->name()\nInherited, see \"The folder\" in Mail::Box\n\n$obj->organization()\nInherited, see \"The folder\" in Mail::Box\n\n$obj->size()\nInherited, see \"The folder\" in Mail::Box\n\n$obj->type()\nInherited, see \"The folder\" in Mail::Box\n\n$obj->update(%options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->url()\nInherited, see \"The folder\" in Mail::Box\n"
                },
                {
                    "name": "Folder flags",
                    "content": "Extends \"Folder flags\" in Mail::Box::Dir.\n\n$obj->access()\nInherited, see \"Folder flags\" in Mail::Box\n\n$obj->isModified()\nInherited, see \"Folder flags\" in Mail::Box\n\n$obj->modified( [BOOLEAN] )\nInherited, see \"Folder flags\" in Mail::Box\n\n$obj->writable()\nInherited, see \"Folder flags\" in Mail::Box\n"
                },
                {
                    "name": "The messages",
                    "content": "Extends \"The messages\" in Mail::Box::Dir.\n\n$obj->current( [$number|$message|$messageid] )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->find($messageid)\nInherited, see \"The messages\" in Mail::Box\n\n$obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->message( $index, [$message] )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->messageId( $messageid, [$message] )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->messageIds()\nInherited, see \"The messages\" in Mail::Box\n\n$obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label| !$label|$filter> )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->nrMessages(%options)\nInherited, see \"The messages\" in Mail::Box\n\n$obj->scanForMessages($message, $messageids, $timespan, $window)\nInherited, see \"The messages\" in Mail::Box\n"
                },
                {
                    "name": "Sub-folders",
                    "content": "Extends \"Sub-folders\" in Mail::Box::Dir.\n\n$obj->listSubFolders(%options)\nMail::Box::Maildir->listSubFolders(%options)\nInherited, see \"Sub-folders\" in Mail::Box\n\n$obj->nameOfSubFolder( $subname, [$parentname] )\nMail::Box::Maildir->nameOfSubFolder( $subname, [$parentname] )\nInherited, see \"Sub-folders\" in Mail::Box\n\n$obj->openRelatedFolder(%options)\nInherited, see \"Sub-folders\" in Mail::Box\n\n$obj->openSubFolder($subname, %options)\nInherited, see \"Sub-folders\" in Mail::Box\n\n$obj->topFolderWithMessages()\nMail::Box::Maildir->topFolderWithMessages()\nInherited, see \"Sub-folders\" in Mail::Box\n"
                },
                {
                    "name": "Internals",
                    "content": "Extends \"Internals\" in Mail::Box::Dir.\n\n$obj->acceptMessages()\nAccept all messages which are waiting in the \"new\" directory to be moved to the \"cur\"\ndirectory. This will not rescan the directory for newly arrived messages, because that's a\ntask for update().\n\nMail::Box::Maildir->appendMessage(%options)\n$obj->coerce($message, %options)\n$obj->create($foldername, %options)\nMail::Box::Maildir->create($foldername, %options)\n-Option   --Defined in--Default\nfolderdir  Mail::Box   undef\n\nfolderdir => DIRECTORY\n\n$obj->createDirs($folderdir)\nMail::Box::Maildir->createDirs($folderdir)\nThe $folderdir contains the absolute path of the location where the messages are kept.\nMaildir folders contain a \"tmp\", \"new\", and \"cur\" sub-directory within that folder directory\nas well. This method will ensure that all directories exist. Returns false on failure.\n\n$obj->determineBodyType($message, $head)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->folderIsEmpty($folderdir)\nMail::Box::Maildir->folderIsEmpty($folderdir)\nChecks whether the folder whose directory is specified as absolute $folderdir is empty or\nnot. A folder is empty when the \"tmp\", \"new\", and \"cur\" subdirectories are empty and some\nfiles which are left there by application programs. The maildir spec explicitly states:\n\".qmail\", \"bulletintime\", \"bulletinlock\" and \"seriallock\". If any other files are found, the\ndirectory is considered not-empty.\n\n$obj->folderToDirectory($foldername, $folderdir)\nInherited, see \"Internals\" in Mail::Box::Dir\n\nMail::Box::Maildir->foundIn( [$foldername], %options )\nInherited, see \"Internals\" in Mail::Box\n\n$obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )\nInherited, see \"Internals\" in Mail::Box\n\n$obj->locker()\nInherited, see \"Internals\" in Mail::Box\n\n$obj->messageInFile($filename)\nInherited, see \"Internals\" in Mail::Box::Dir\n\n$obj->read(%options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->readMessageFilenames($directory)\nInherited, see \"Internals\" in Mail::Box::Dir\n\n$obj->readMessages(%options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->storeMessage($message)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->toBeThreaded($messages)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->toBeUnthreaded($messages)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->updateMessages(%options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->write(%options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->writeMessages(%options)\nInherited, see \"Internals\" in Mail::Box\n"
                },
                {
                    "name": "Other methods",
                    "content": "Extends \"Other methods\" in Mail::Box::Dir.\n\n$obj->timespan2seconds($time)\nMail::Box::Maildir->timespan2seconds($time)\nInherited, see \"Other methods\" in Mail::Box\n"
                },
                {
                    "name": "Error handling",
                    "content": "Extends \"Error handling\" in Mail::Box::Dir.\n\n$obj->AUTOLOAD()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->addReport($object)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )\nMail::Box::Maildir->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->errors()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->log( [$level, [$strings]] )\nMail::Box::Maildir->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Box::Maildir->logPriority($level)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logSettings()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->notImplemented()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->report( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->reportAll( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->trace( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->warnings()\nInherited, see \"Error handling\" in Mail::Reporter\n"
                },
                {
                    "name": "Cleanup",
                    "content": "Extends \"Cleanup\" in Mail::Box::Dir.\n\n$obj->DESTROY()\nInherited, see \"Cleanup\" in Mail::Box\n"
                }
            ]
        },
        "DETAILS": {
            "content": "The explanation is complicated, but for normal use you should bother yourself with all details.\n\nExtends \"DETAILS\" in Mail::Box::Dir.\n",
            "subsections": [
                {
                    "name": "Different kinds of folders",
                    "content": "Extends \"Different kinds of folders\" in Mail::Box::Dir.\n"
                },
                {
                    "name": "Available folder types",
                    "content": "Extends \"Available folder types\" in Mail::Box::Dir.\n"
                },
                {
                    "name": "Folder class implementation",
                    "content": "Extends \"Folder class implementation\" in Mail::Box::Dir.\n"
                },
                {
                    "name": "How MAILDIR folders work",
                    "content": "Maildir-type folders use a directory to store the messages of one folder. Each message is stored\nin a separate file. This seems useful, because changes in a folder change only a few of these\nsmall files, in contrast with file-based folders where changes in a folder cause rewrites of\nhuge folder-files.\n\nHowever, Maildir based folders perform very bad if you need header information of all messages.\nFor instance, if you want to have full knowledge about all message-threads (see\nMail::Box::Thread::Manager) in the folder, it requires to read all header lines in all message\nfiles. And usually, reading your messages as threads is desired. Maildir maintains a tiny amount\nof info visible in the filename, which may make it perform just a little bit faster than MH.\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "Error: Cannot append Maildir message in $new to folder $self.\nThe message (or messages) could not be stored in the right directories for the Maildir\nfolder.\n\nError: Cannot create Maildir directory $dir: $!\nA Maildir folder is represented by a directory, with some sub-directories. The top folder\ndirectory could not be created for the reason indicated.\n\nError: Cannot create Maildir folder $name.\nOne or more of the directories required to administer a Maildir folder could not be created.\n\nError: Cannot create Maildir message file $new.\nA message is converted from some other message format into a Maildir format by writing it to\na file with a name which contains the status flags of the message. Apparently, creating this\nfile failed.\n\nError: Cannot create Maildir subdir $dir: $!\nEach Maildir folder has three sub-directories for administration: \"new\", \"tmp\", and \"cur\".\nThe mentioned directory could not be created for the indicated reason.\n\nWarning: Changes not written to read-only folder $self.\nYou have opened the folder read-only --which is the default set by new(access)--, made\nmodifications, and now want to close it. Set close(force) if you want to overrule the access\nmode, or close the folder with close(write) set to \"NEVER\".\n\nError: Copying failed for one message.\nFor some reason, for instance disc full, removed by external process, or read-protection, it\nis impossible to copy one of the messages. Copying will proceed for the other messages.\n\nError: Destination folder $name is not writable.\nThe folder where the messages are copied to is not opened with write access (see\nnew(access)). This has no relation with write permission to the folder which is controlled\nby your operating system.\n\nWarning: Different messages with id $msgid\nThe message id is discovered more than once within the same folder, but the content of the\nmessage seems to be different. This should not be possible: each message must be unique.\n\nError: Folder $name is opened read-only\nYou can not write to this folder unless you have opened the folder to write or append with\nnew(access), or the \"force\" option is set true.\n\nError: Folder $name not deleted: not writable.\nThe folder must be opened with write access via new(access), otherwise removing it will be\nrefused. So, you may have write-access according to the operating system, but that will not\nautomatically mean that this \"delete\" method permits you to. The reverse remark is valid as\nwell.\n\nError: Invalid timespan '$timespan' specified.\nThe string does not follow the strict rules of the time span syntax which is permitted as\nparameter.\n\nWarning: Message-id '$msgid' does not contain a domain.\nAccording to the RFCs, message-ids need to contain a unique random part, then an \"@\", and\nthen a domain name. This is made to avoid the creation of two messages with the same id. The\nwarning emerges when the \"@\" is missing from the string.\n\nError: Package $package does not implement $method.\nFatal error: the specific package (or one of its superclasses) does not implement this\nmethod where it should. This message means that some other related classes do implement this\nmethod however the class at hand does not. Probably you should investigate this and probably\ninform the author of the package.\n\nError: Unable to create subfolder $name of $folder.\nThe copy includes the subfolders, but for some reason it was not possible to copy one of\nthese. Copying will proceed for all other sub-folders.\n\nError: Writing folder $name failed\nFor some reason (you probably got more error messages about this problem) it is impossible\nto write the folder, although you should because there were changes made.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "This module is part of Mail-Box distribution version 3.009, built on August 18, 2020. Website:\nhttp://perl.overmeer.net/CPAN/\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see ChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself. See http://dev.perl.org/licenses/\n",
            "subsections": []
        }
    },
    "summary": "Mail::Box::Maildir - handle Maildir folders",
    "flags": [],
    "examples": [],
    "see_also": []
}