1Mail::Box-Cookbook(3) User Contributed Perl DocumentationMail::Box-Cookbook(3)
2
3
4

NAME

6       Mail::Box-Cookbook - Examples how to use Mail::Box
7

DESCRIPTION

9       The Mail::Box package is a suite of classes for accessing and managing
10       email folders in a folder-independent manner.  This manual demonstrates
11       a few simple applications.  Please contribute with examples and fixes.
12       It may also help to have a look at the programs included in the
13       "scripts/" and the "examples/" directories of the distribution.
14
15   The Manager
16       For more details about all the packages which are involved in the
17       Mail::Box suite you have to read Mail::Box-Overview.  But you do not
18       need to know much if you want to use the Mail::Box suite.
19
20       Please use the manager to open your folders.  You will certainly
21       benefit from it.  The manager takes care of detecting which folder type
22       you are using, and which folders are open.  The latter avoids the
23       accidental re-opening of an already open folder.
24
25       The "examples/open.pl" script contains mainly
26
27        my $mgr    = Mail::Box::Manager->new;
28        my $folder = $mgr->open($filename);
29        foreach my $message ($folder->messages) {
30            print $message->get('Subject') || '<no subject>', "\n";
31        }
32        $folder->close;
33
34       which shows all the most important functions.  It will cause all
35       subjects of the messages in the indicated folder to be listed.  So:
36       although the number of packages included in the Mail::Box module is
37       huge, only little is needed for normal programs.
38
39       In stead of calling "close" on the folder, you may also call
40
41        $mgr->closeAllFolders;
42
43       If you forget to close a folder, changes will not be written.  This may
44       change in the future.
45
46   Multi part messages
47       In early days of Internet, multi-part messages were very rare.
48       However, in recent years, a large deal of all transmitted message have
49       attachments.  This makes handling of the bodies of messages a bit
50       harder: when a message contains more than one part, which part is then
51       the most important to read?
52
53       To complicate life, multi-parts can be nested: each part may be a
54       multi-part by itself.  This means that programs handling the message
55       content must be recursive or skip multi-parts.
56
57       The central part of the "examples/multipart.pl" script reads:
58
59        foreach my $message ($folder->messages) {
60            show_type($message);
61        }
62
63        show_type($) {
64            my $msg = shift;
65            print $msg->get('Content-Type'), "\n";
66
67            if($msg->isMultipart) {
68                foreach my $part ($msg->parts) {
69                    show_type($part);
70                }
71            }
72        }
73
74       Each part is a message by itself. It has a header and a body.  A
75       multipart message has a special body: it contains a list of parts and
76       optionally also a preamble and an epilogue, which are respectively the
77       lines before and after the parts.  These texts may be ignored, because
78       they are only descriptive on how the multi-part was created.
79
80   Filter
81       The target is to select a few messages from one folder, to move them to
82       an other.  The "examples/takelarge.pl" script demonstrates how to
83       achieve this.  Be warned: it will replace your input folder!
84
85       As abstract of the crucial part:
86
87        my $inbox = $mgr->open('inbox', access => 'rw');
88        my $large = $mgr->open('large', access => 'a', create => 1);
89
90        foreach my $message ($inbox->messages) {
91            next if $message->size < $size;
92            $mgr->moveMessage($large, $message);
93        }
94
95        $inbox->close;
96        $large->close;
97
98       The "inbox" is opened for read and write: first read all messages, and
99       then write the smaller folder without moved messages back.  The "large"
100       folder is created if the file does not exist yet.  In any case,
101       messages will be added to the end of the folder.
102
103       The manager is needed to move the message: to unregister the message
104       from the first folder, and reregister it in the second.  You can move
105       more messages at once, if you like.  When you move to a folder which is
106       not open, you even better do that: it will be faster:
107
108        my @move = grep {$_->size >= $size} $inbox->messages;
109        $mgr->moveMessage($large, @move);
110
111       In this example, the "size" of the message determines whether the
112       message is moved or not.  Of course, there are many other criteria you
113       can use.  For instance, use "timestamp" to find old messages:
114
115        use constant YEAR => 365 * 24 * 60 * 60;
116        my $now = time;
117        my @old = grep {$_->timestamp - $now > YEAR} $inbox->messages;
118        $mgr->moveMessage($oldbox, @old);
119
120   Create a reply
121       The complex message treatment is implemented in
122       Mail::Message::Construct and automatically loaded when needed.  It is
123       sufficient to simply call "reply" on any message:
124
125        my $folder  = ...;
126        my $message = $folder->message(8);
127        my $reply   = $message->reply;
128
129        $folder->addMessage($reply);
130        $reply->print;
131
132       The method is quite complex, as demonstrated by "examples/reply.pl", in
133       which the construction of a reply-message is shown.
134
135       Three kinds of reply messages can be made: one which does not include
136       the original message at all (NO), then one which inlines the original
137       message quoted (INLINE), and as third possibility the original message
138       as attachment (ATTACH).
139
140       The "include" parameter selects the kind of reply.  When you reply to
141       binary or multi-part messages, INLINE will automatically promoted to
142       ATTACH.  By default text will be stripped from the original senders
143       signature.  Multi-part messages are stripped from attachments which
144       qualify as signature.  In case a multi-part (after stripping) only
145       contains one part, and that INLINE is requested, it will be
146       'flattened': the reply may be a single-part.
147
148       Have a look at the parameters which can be passed to reply in
149       Mail::Message::Construct.  For a single-part reply, the return will be
150
151        prelude
152        quoted original
153        postlude
154        --
155        signature
156
157       A multipart body will be
158
159        part 1: prelude
160                [ see attachment ]
161                postlude
162        part 2: stripped original multipart
163        part 3: signature
164
165   Build a message
166       There are three ways to create a message which is not a reply:
167
168Mail::Message::buildFromBody()
169
170           Start with creating a body, and transform that into a message.
171
172Mail::Message::build()
173
174           create the whole message at once.
175
176Mail::Message::read()
177
178           read a message from a file-handle, scalar, or array of lines.
179
180       All three methods are implemented in Mail::Message::Construct.  Please,
181       do yourself a favor, and give preference to the "build*" methods, over
182       the "read", because they are much more powerful.  Use the "read" only
183       when you have the message on STDIN or an array of lines which is
184       supplied by an external program.
185
186       Very important to remember from now on: information about the content
187       of the body (the "Content-*" lines in the header) is stored within the
188       body object, for as long as the body is not contained with a message
189       object.
190
191       For instance, $message method "decoded" returns the decoded body of the
192       $message.  It is a body object by itself, however outside a real
193       message.  Then you may want to play around with it, by concatenating
194       some texts: again resulting in a new body.  Each body contains the
195       right "Content-*" information.  Then, finally, you create a message
196       specifying the body and extra header lines.  At that moment you need to
197       specify the source and destination addresses (the "From" and "To"
198       lines>).  At that moment, the body will automatically be encoded to be
199       acceptable for mail folders and transmission programs.
200
201        my $body = Mail::Message::Body->new
202         ( mime_type         => 'text/css'
203         , transfer_encoding => '8bit'
204         , data              => \@lines
205         );
206
207       Above example creates a body, with explicitly stating what kind of data
208       is stored in it.  The default mime type is "text/plain".  The transfer
209       encoding defaults to "none".  Each message will get encoded on the
210       moment it is added to a message.  The default encoding depends on the
211       mime type.
212
213       To start with the first way to create a message.  This solution
214       provides maximum control over the message creation.  Quite some work is
215       hidden for you when executing the next line.
216
217        my $message = Mail::Message->buildFromBody
218          ( $body
219          , From => 'me@example.com'
220          , To   => 'you@anywhere.net'
221          , Cc   => [ Mail::Address->parse($groupalias) ]
222          );
223
224       For header lines, you may specify a string, an address object
225       (Mail::Address), or an array of such addresses.  If you want to create
226       multi-part messages, you need to create a multi-part body yourself
227       first.
228
229       The second way of constructing a message uses the "build" method.  A
230       demonstration can be found in "examples/build.pl".  In only one class
231       method call the header and the (possible multi-parted) body is created.
232
233       With the "data" option, you can specify one scalar which contains a
234       whole body or an array of lines.  Using the "file" option, a file-
235       handle or filename specifies a body.  The "attach" option refers to
236       construed bodies and messages.  Each option can be used as often as
237       needed.  If more than one source of data is provided, a multi-part
238       message is produced.
239
240        my $message = Mail::Message->build
241         ( From       => 'me@example.com'
242         , To         => 'you@anywhere.net'
243         , 'X-Mailer' => 'Automatic mailing system'
244         , data       => \@lines
245         , file       => 'logo.jpg'
246         , attach     => $signature_body
247         );
248

SEE ALSO

250       This module is part of Mail-Box distribution version 3.010, built on
251       July 18, 2023. Website: http://perl.overmeer.net/CPAN/
252

LICENSE

254       Copyrights 2001-2023 by [Mark Overmeer]. For other contributors see
255       ChangeLog.
256
257       This program is free software; you can redistribute it and/or modify it
258       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
259
260
261
262perl v5.38.0                      2023-07-24             Mail::Box-Cookbook(3)
Impressum