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