1MboxParser::Mail(3)   User Contributed Perl Documentation  MboxParser::Mail(3)
2
3
4

NAME

6       Mail::MboxParser::Mail - Provide mail-objects and methods upon
7

SYNOPSIS

9       See Mail::MboxParser for an outline on usage. Examples however are also
10       provided in this manpage further below.
11

DESCRIPTION

13       Mail::MboxParser::Mail objects are usually not created directly though,
14       in theory, they could be. A description of the provided methods can be
15       found in Mail::MboxParser.
16
17       However, go on reading if you want to use methods from MIME::Entity and
18       learn about overloading.
19

METHODS

21       new(header, body)
22           This is usually not called directly but instead by
23           "get_messages()". You could however create a mail-object manually
24           providing the header and body each as either one string or as an
25           array-ref representing the lines.
26
27           Here is a common scenario: Retrieving mails from a remote POP-
28           server using Mail::POP3Client and directly feeding each mail to
29           "Mail::MboxParser::Mail->new":
30
31               use Mail::POP3Client;
32               use Mail::MboxParser::Mail;
33
34               my $pop = new Mail::POP3Client (...);
35
36               for my $i (1 .. $pop->Count) {
37                   my $msg = Mail::MboxParser::Mail->new( [ $pop->Head($i) ],
38                                                          [ $pop->Body($i) ] );
39                   $msg->store_all_attachments( path => '/home/user/dump' );
40               }
41
42           The above effectively behaves like an attachment-only retriever.
43
44       header
45           Returns the mail-header as a hash-ref with header-fields as keys.
46           All keys are turned to lower-case, so $header{Subject} has to be
47           written as $header{subject}.
48
49           If a header-field occurs more than once in the header, the value of
50           the key is an array_ref. Example:
51
52               my $field = $msg->header->{field};
53               print $field->[0]; # first occurance of 'field'
54               print $field->[1]; # second one
55               ...
56
57       from_line
58           Returns the "From "-line of the message.
59
60       trace
61           This method returns the "Received: "-lines of the message as a
62           list.
63
64       body
65       body(n)
66           Returns a Mail::MboxParser::Mail::Body object. For methods upon
67           that see further below. When called with the argument n, the n-th
68           body of the message is retrieved. That is, the body of the n-th
69           entity.
70
71           Sets "$mail->error" if something went wrong.
72
73       find_body
74           This will return an index number that represents what
75           Mail::MboxParser::Mail considers to be the actual (main)-body of an
76           email. This is useful if you don't know about the structure of a
77           message but want to retrieve the message's signature for instance:
78
79                   $signature = $msg->body($msg->find_body)->signature;
80
81           Changes are good that find_body does what it is supposed to do.
82
83       make_convertable
84           Returns a Mail::MboxParser::Mail::Convertable object. For details
85           on what you can do with it, read
86           Mail::MboxParser::Mail::Convertable.
87
88       get_field(headerfield)
89           Returns the specified raw field from the message header, that is:
90           the fieldname is not stripped off nor is any decoding done. Returns
91           multiple lines as needed if the field is "Received" or another
92           multi-line field.  Not case sensitive.
93
94           "get_field()" always returns one string regardless of how many
95           times the field occured in the header. Multiple occurances are
96           separated by a newline and multiple whitespaces squeezed to one.
97           That means you can process each occurance of the field thusly:
98
99               for my $field ( split /\n/, $msg->get_field('received') ) {
100                   # do something with $field
101               }
102
103           Sets "$mail->error" if the field was not found in which case
104           "get_field()" returns "undef".
105
106       from
107           Returns a hash-ref with the two fields 'name' and 'email'. Returns
108           "undef" if empty. The name-field does not necessarily contain a
109           value either. Example:
110
111                   print $mail->from->{email};
112
113           On behalf of suggestions I received from users, from() tries to be
114           smart when 'name'is empty and 'email' has the form
115           'first.name@host.com'. In this case, 'name' is set to "First Name".
116
117       to  Returns an array of hash-references of all to-fields in the mail-
118           header. Fields are the same as those of "$mail->from". Example:
119
120                   for my $recipient ($mail->to) {
121                           print $recipient->{name} || "<no name>", "\n";
122                           print $recipient->{email};
123                   }
124
125           The same 'name'-smartness applies here as described under "from()".
126
127       cc  Identical with to() but returning the hash-refed "Cc: "-line.
128
129           The same 'name'-smartness applies here as described under "from()".
130
131       id  Returns the message-id of a message cutting off the leading and
132           trailing '<' and '>' respectively.
133
134       num_entities
135           Returns the number of MIME-entities. That is, the number of sub-
136           entitities actually. If 0 is returned and you think this is wrong,
137           check "$mail->log".
138
139       get_entities
140       get_entities(n)
141           Either returns an array of all MIME::Entity objects or one
142           particular if called with a number. If no entity whatsoever could
143           be found, an empty list is returned.
144
145           "$mail->log" instantly called after get_entities will give you some
146           information of what internally may have failed. If set, this will
147           be an error raised by MIME::Entity but you don't need to worry
148           about it at all. It's just for the record.
149
150       get_entity_body(n)
151           Returns the body of the n-th MIME::Entity as a single string, undef
152           otherwise in which case you could check "$mail->error".
153
154       store_entity_body(n, handle => FILEHANDLE)
155           Stores the stringified body of n-th entity to the specified
156           filehandle. That's basically the same as:
157
158            my $body = $mail->get_entity_body(0);
159            print FILEHANDLE $body;
160
161           and could be shortened to this:
162
163            $mail->store_entity_body(0, handle => \*FILEHANDLE);
164
165           It returns a true value on success and undef on failure. In this
166           case, examine the value of $mail->error since the entity you
167           specified with 'n' might not exist.
168
169       store_attachment(n)
170       store_attachment(n, options)
171           It is really just a call to store_entity_body but it will take care
172           that the n-th entity really is a saveable attachment. That is, it
173           wont save anything with a MIME-type of, say, text/html or so.
174
175           Unless further 'options' have been given, an attachment (if found)
176           is stored into the current directory under the recommended filename
177           given in the MIME-header. 'options' are specified in key/value
178           pairs:
179
180               key:       | value:        | description:
181               ===========|================|===============================
182               path       | relative or    | directory to store attachment
183               (".")      | absolute       |
184                          | path           |
185               -----------|----------------|-------------------------------
186               encode     | encoding       | Some platforms store files
187                          | suitable for   | in e.g. UTF-8. Specify the
188                          | Encode::encode | appropriate encoding here and
189                          |                | and the filename will be en-
190                          |                | coded accordingly.
191               -----------|----------------|-------------------------------
192               store_only | a compiled     | store only files whose file
193                          | regex-pattern  | names match this pattern
194               -----------|----------------|-------------------------------
195               code       | an anonym      | first argument will be the
196                          | subroutine     | $msg-object, second one the
197                          |                | index-number of the current
198                          |                | MIME-part
199                          |                | should return a filename for
200                          |                | the attachment
201               -----------|----------------|-------------------------------
202               prefix     | prefix for     | all filenames are prefixed
203                          | filenames      | with this value
204               -----------|----------------|-------------------------------
205               args       | additional     | this array-ref will be passed
206                          | arguments as   | on to the 'code' subroutine
207                          | array-ref      | as a dereferenced array
208
209           Example:
210
211                   $msg->store_attachment(1,
212                                       path => "/home/ethan/",
213                                       code => sub {
214                                                   my ($msg, $n, @args) = @_;
215                                                   return $msg->id."+$n";
216                                                   },
217                                       args => [ "Foo", "Bar" ]);
218
219           This will save the attachment found in the second entity under the
220           name that consists of the message-ID and the appendix "+1" since
221           the above code works on the second entity (that is, with index =
222           1). 'args' isn't used in this example but should demonstrate how to
223           pass additional arguments. Inside the 'code' sub, @args equals
224           ("Foo", "Bar").
225
226           If 'path' does not exist, it will try to create the directory for
227           you.
228
229           You can specify to save only files matching a certain pattern. To
230           do that, use the store-only switch:
231
232               $msg->store_attachment(1, path       => "/home/ethan/",
233                                         store_only => qr/\.jpg$/i);
234
235           The above will only save files that end on '.jpg', not case-
236           sensitive. You could also use a non-compiled pattern if you want,
237           but that would make for instance case-insensitive matching a little
238           cumbersome:
239
240               store_only => '(?i)\.jpg$'
241
242           If you are working on a platform that requires a certain encoding
243           for filenames on disk, you can use the 'encode' option. This
244           becomes necessary for instance on Mac OS X which internally is
245           UTF-8 based. If the filename contains 8bit characters (like the
246           German umlauts or French accented characters as in 'é'), storing
247           the attachment under a non-encoded name will most likely fail. In
248           this case, use something like this:
249
250               $msg->store_attachment(1, path => '/tmp', encode => 'utf-8');
251
252           See Encode::Supported for a list of encodings that you may use.
253
254           Returns the filename under which the attachment has been saved.
255           undef is returned in case the entity did not contain a saveable
256           attachement, there was no such entity at all or there was something
257           wrong with the 'path' you specified. Check "$mail->error" to find
258           out which of these possibilities apply.
259
260       store_all_attachments
261       store_all_attachments(options)
262           Walks through an entire mail and stores all apparent attachments.
263           'options' are exactly the same as in "store_attachement()" with the
264           same behaviour if no options are given.
265
266           Returns a list of files that have been succesfully saved and an
267           empty list if no attachment could be extracted.
268
269           "$mail->error" will tell you possible failures and a possible
270           explanation for that.
271
272       get_attachments
273       get_attachments(file)
274           This method returns a mapping from attachment-names (if those are
275           savable) to index-numbers of the MIME-part that represents this
276           attachment. It returns a hash-reference, the file-names being the
277           key and the index the value:
278
279               my $mapping = $msg->get_attachments;
280               for my $filename (keys %$mapping) {
281                   print "$filename => $mapping->{$filename}\n";
282               }
283
284           If called with a string as argument, it tries to look up this
285           filename. If it can't be found, undef is returned. In this case you
286           also should have an error-message patiently awaiting you in the
287           return value of "$mail->error".
288
289           Even though it looks tempting, don't do the following:
290
291               # BAD!
292
293               for my $file (qw/file1.ext file2.ext file3.ext file4.ext/) {
294                   print "$file is in message ", $msg->id, "\n"
295                       if defined $msg->get_attachments($file);
296               }
297
298           The reason is that "get_attachments()" is currently not optimized
299           to cache the filename mapping. So, each time you call it on (even
300           the same) message, it will scan it from beginning to end. Better
301           would be:
302
303               # GOOD!
304
305               my $mapping = $msg->get_attachments;
306               for my $file (qw/file1.ext file2.ext file3.ext file4.ext/) {
307                   print "$file is in message ", $msg->id, "\n"
308                       if exists $mapping->{$file};
309               }
310
311       as_string
312           Returns the message as one string. This is the method that string
313           overloading depends on, so these two are the same:
314
315               print $msg;
316
317               print $msg->as_string;
318

EXTERNAL METHODS

320       Mail::MboxParser::Mail implements an autoloader that will do the
321       appropriate type-casts for you if you invoke methods from external
322       modules. This, however, currently only works with MIME::Entity. Support
323       for other modules will follow.  Example:
324
325               my $mb = Mail::MboxParser->new("/home/user/Mail/received");
326               for my $msg ($mb->get_messages) {
327                       print $msg->effective_type, "\n";
328               }
329
330       "effective_type()" is not implemented by Mail::MboxParser::Mail and
331       thus the corresponding method of MIME::Entity is automatically called.
332
333       To learn about what methods might be useful for you, you should read
334       the "Access"-part of the section "PUBLIC INTERFACE" in the MIME::Entity
335       manpage.  It may become handy if you have mails with a lot of MIME-
336       parts and you not just want to handle binary-attachments but any kind
337       of MIME-data.
338

OVERLOADING

340       Mail::MboxParser::Mail overloads the " " operator. Overloading
341       operators is a fancy feature of Perl and some other languages (C++ for
342       instance) which will change the behaviour of an object when one of
343       those overloaded operators is applied onto it. Here you get the
344       stringified mail when you write $mail while otherwise you'd get the
345       stringified reference: "Mail::MboxParser::Mail=HASH(...)".
346

VERSION

348       This is version 0.55.
349
351       Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>
352
353       Copyright (c)  2001-2005 Tassilo von Parseval.  This program is free
354       software; you can redistribute it and/or modify it under the same terms
355       as Perl itself.
356

SEE ALSO

358       MIME::Entity
359
360       Mail::MboxParser, Mail::MboxParser::Mail::Body,
361       Mail::MboxParser::Mail::Convertable
362
363
364
365perl v5.32.1                      2021-01-27               MboxParser::Mail(3)
Impressum