{
    "mode": "perldoc",
    "parameter": "Mail::Box-Cookbook",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3ABox-Cookbook/json",
    "generated": "2026-06-14T07:48:59Z",
    "sections": {
        "NAME": {
            "content": "Mail::Box-Cookbook - Examples how to use Mail::Box\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The Mail::Box package is a suite of classes for accessing and managing email folders in a\nfolder-independent manner. This manual demonstrates a few simple applications. Please contribute\nwith examples and fixes. It may also help to have a look at the programs included in the\n\"scripts/\" and the \"examples/\" directories of the distribution.\n",
            "subsections": [
                {
                    "name": "The Manager",
                    "content": "For more details about all the packages which are involved in the Mail::Box suite you have to\nread Mail::Box-Overview. But you do not need to know much if you want to use the Mail::Box\nsuite.\n\nPlease use the manager to open your folders. You will certainly benefit from it. The manager\ntakes care of detecting which folder type you are using, and which folders are open. The latter\navoids the accidental re-opening of an already open folder.\n\nThe \"examples/open.pl\" script contains mainly\n\nmy $mgr    = Mail::Box::Manager->new;\nmy $folder = $mgr->open($filename);\nforeach my $message ($folder->messages) {\nprint $message->get('Subject') || '<no subject>', \"\\n\";\n}\n$folder->close;\n\nwhich shows all the most important functions. It will cause all subjects of the messages in the\nindicated folder to be listed. So: although the number of packages included in the Mail::Box\nmodule is huge, only little is needed for normal programs.\n\nIn stead of calling \"close\" on the folder, you may also call\n\n$mgr->closeAllFolders;\n\nIf you forget to close a folder, changes will not be written. This may change in the future.\n"
                },
                {
                    "name": "Multi part messages",
                    "content": "In early days of Internet, multi-part messages were very rare. However, in recent years, a large\ndeal of all transmitted message have attachments. This makes handling of the bodies of messages\na bit harder: when a message contains more than one part, which part is then the most important\nto read?\n\nTo complicate life, multi-parts can be nested: each part may be a multi-part by itself. This\nmeans that programs handling the message content must be recursive or skip multi-parts.\n\nThe central part of the \"examples/multipart.pl\" script reads:\n\nforeach my $message ($folder->messages) {\nshowtype($message);\n}\n\nshowtype($) {\nmy $msg = shift;\nprint $msg->get('Content-Type'), \"\\n\";\n\nif($msg->isMultipart) {\nforeach my $part ($msg->parts) {\nshowtype($part);\n}\n}\n}\n\nEach part is a message by itself. It has a header and a body. A multipart message has a special\nbody: it contains a list of parts and optionally also a preamble and an epilogue, which are\nrespectively the lines before and after the parts. These texts may be ignored, because they are\nonly descriptive on how the multi-part was created.\n"
                },
                {
                    "name": "Filter",
                    "content": "The target is to select a few messages from one folder, to move them to an other. The\n\"examples/takelarge.pl\" script demonstrates how to achieve this. Be warned: it will replace your\ninput folder!\n\nAs abstract of the crucial part:\n\nmy $inbox = $mgr->open('inbox', access => 'rw');\nmy $large = $mgr->open('large', access => 'a', create => 1);\n\nforeach my $message ($inbox->messages) {\nnext if $message->size < $size;\n$mgr->moveMessage($large, $message);\n}\n\n$inbox->close;\n$large->close;\n\nThe \"inbox\" is opened for read and write: first read all messages, and then write the smaller\nfolder without moved messages back. The \"large\" folder is created if the file does not exist\nyet. In any case, messages will be added to the end of the folder.\n\nThe manager is needed to move the message: to unregister the message from the first folder, and\nreregister it in the second. You can move more messages at once, if you like. When you move to a\nfolder which is not open, you even better do that: it will be faster:\n\nmy @move = grep {$->size >= $size} $inbox->messages;\n$mgr->moveMessage($large, @move);\n\nIn this example, the \"size\" of the message determines whether the message is moved or not. Of\ncourse, there are many other criteria you can use. For instance, use \"timestamp\" to find old\nmessages:\n\nuse constant YEAR => 365 * 24 * 60 * 60;\nmy $now = time;\nmy @old = grep {$->timestamp - $now > YEAR} $inbox->messages;\n$mgr->moveMessage($oldbox, @old);\n"
                },
                {
                    "name": "Create a reply",
                    "content": "The complex message treatment is implemented in Mail::Message::Construct and automatically\nloaded when needed. It is sufficient to simply call \"reply\" on any message:\n\nmy $folder  = ...;\nmy $message = $folder->message(8);\nmy $reply   = $message->reply;\n\n$folder->addMessage($reply);\n$reply->print;\n\nThe method is quite complex, as demonstrated by \"examples/reply.pl\", in which the construction\nof a reply-message is shown.\n\nThree kinds of reply messages can be made: one which does not include the original message at\nall (NO), then one which inlines the original message quoted (INLINE), and as third possibility\nthe original message as attachment (ATTACH).\n\nThe \"include\" parameter selects the kind of reply. When you reply to binary or multi-part\nmessages, INLINE will automatically promoted to ATTACH. By default text will be stripped from\nthe original senders signature. Multi-part messages are stripped from attachments which qualify\nas signature. In case a multi-part (after stripping) only contains one part, and that INLINE is\nrequested, it will be 'flattened': the reply may be a single-part.\n\nHave a look at the parameters which can be passed to reply in Mail::Message::Construct. For a\nsingle-part reply, the return will be\n\nprelude\nquoted original\npostlude\n--\nsignature\n\nA multipart body will be\n\npart 1: prelude\n[ see attachment ]\npostlude\npart 2: stripped original multipart\npart 3: signature\n"
                },
                {
                    "name": "Build a message",
                    "content": "There are three ways to create a message which is not a reply:\n\n*   Mail::Message::buildFromBody()\n\nStart with creating a body, and transform that into a message.\n\n*   Mail::Message::build()\n\ncreate the whole message at once.\n\n*   Mail::Message::read()\n\nread a message from a file-handle, scalar, or array of lines.\n\nAll three methods are implemented in Mail::Message::Construct. Please, do yourself a favor, and\ngive preference to the \"build*\" methods, over the \"read\", because they are much more powerful.\nUse the \"read\" only when you have the message on STDIN or an array of lines which is supplied by\nan external program.\n\nVery important to remember from now on: information about the content of the body (the\n\"Content-*\" lines in the header) is stored within the body object, for as long as the body is\nnot contained with a message object.\n\nFor instance, $message method \"decoded\" returns the decoded body of the $message. It is a body\nobject by itself, however outside a real message. Then you may want to play around with it, by\nconcatenating some texts: again resulting in a new body. Each body contains the right\n\"Content-*\" information. Then, finally, you create a message specifying the body and extra\nheader lines. At that moment you need to specify the source and destination addresses (the\n\"From\" and \"To\" lines>). At that moment, the body will automatically be encoded to be acceptable\nfor mail folders and transmission programs.\n\nmy $body = Mail::Message::Body->new\n( mimetype         => 'text/css'\n, transferencoding => '8bit'\n, data              => \\@lines\n);\n\nAbove example creates a body, with explicitly stating what kind of data is stored in it. The\ndefault mime type is \"text/plain\". The transfer encoding defaults to \"none\". Each message will\nget encoded on the moment it is added to a message. The default encoding depends on the mime\ntype.\n\nTo start with the first way to create a message. This solution provides maximum control over the\nmessage creation. Quite some work is hidden for you when executing the next line.\n\nmy $message = Mail::Message->buildFromBody\n( $body\n, From => 'me@example.com'\n, To   => 'you@anywhere.net'\n, Cc   => [ Mail::Address->parse($groupalias) ]\n);\n\nFor header lines, you may specify a string, an address object (Mail::Address), or an array of\nsuch addresses. If you want to create multi-part messages, you need to create a multi-part body\nyourself first.\n\nThe second way of constructing a message uses the \"build\" method. A demonstration can be found\nin \"examples/build.pl\". In only one class method call the header and the (possible multi-parted)\nbody is created.\n\nWith the \"data\" option, you can specify one scalar which contains a whole body or an array of\nlines. Using the \"file\" option, a file-handle or filename specifies a body. The \"attach\" option\nrefers to construed bodies and messages. Each option can be used as often as needed. If more\nthan one source of data is provided, a multi-part message is produced.\n\nmy $message = Mail::Message->build\n( From       => 'me@example.com'\n, To         => 'you@anywhere.net'\n, 'X-Mailer' => 'Automatic mailing system'\n, data       => \\@lines\n, file       => 'logo.jpg'\n, attach     => $signaturebody\n);\n"
                }
            ]
        },
        "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-Cookbook - Examples how to use Mail::Box",
    "flags": [],
    "examples": [],
    "see_also": []
}