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 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 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 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 The "examples/open.pl" script contains mainly
26 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 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 In stead of calling "close" on the folder, you may also call
40 $mgr->closeAllFolders;
42 If you forget to close a folder, changes will not be written. This may
44 change in the future.
45 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 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 The central part of the "examples/multipart.pl" script reads:
58 foreach my $message ($folder->messages) {
60 show_type($message);
61 }
62 show_type($) {
64 my $msg = shift;
65 print $msg->get('Content-Type'), "\n";
66 if($msg->isMultipart) {
68 foreach my $part ($msg->parts) {
69 show_type($part);
70 }
71 }
72 }
73 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 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 As abstract of the crucial part:
86 my $inbox = $mgr->open('inbox', access => 'rw');
88 my $large = $mgr->open('large', access => 'a', create => 1);
89 foreach my $message ($inbox->messages) {
91 next if $message->size < $size;
92 $mgr->moveMessage($large, $message);
93 }
94 $inbox->close;
96 $large->close;
97 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 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 my @move = grep {$_->size >= $size} $inbox->messages;
109 $mgr->moveMessage($large, @move);
110 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 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 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 my $folder = ...;
126 my $message = $folder->message(8);
127 my $reply = $message->reply;
128 $folder->addMessage($reply);
130 $reply->print;
131 The method is quite complex, as demonstrated by "examples/reply.pl", in
133 which the construction of a reply-message is shown.
134 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 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 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 prelude
152 quoted original
153 postlude
154 --
155 signature
156 A multipart body will be
158 part 1: prelude
160 [ see attachment ]
161 postlude
162 part 2: stripped original multipart
163 part 3: signature
164 Build a message
166 There are three ways to create a message which is not a reply:
167 • Mail::Message::buildFromBody()
169 Start with creating a body, and transform that into a message.
171 • Mail::Message::build()
173 create the whole message at once.
175 • Mail::Message::read()
177 read a message from a file-handle, scalar, or array of lines.
179 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 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 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 my $body = Mail::Message::Body->new
202 ( mime_type => 'text/css'
203 , transfer_encoding => '8bit'
204 , data => \@lines
205 );
206 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 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 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 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 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 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 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
250 This module is part of Mail-Box distribution version 3.009, built on
251 August 18, 2020. Website: http://perl.overmeer.net/CPAN/
252
254 Copyrights 2001-2020 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 http://dev.perl.org/licenses/
259perl v5.34.0 2021-07-22 Mail::Box-Cookbook(3)