1MboxParser::Mail(3) User Contributed Perl Documentation MboxParser::Mail(3)
2
6 Mail::MboxParser::Mail - Provide mail-objects and methods upon
7
9 See Mail::MboxParser for an outline on usage. Examples however are also
10 provided in this manpage further below.
11
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 However, go on reading if you want to use methods from MIME::Entity and
18 learn about overloading.
19
21 new(header, body)
22 This is usually not called directly but instead by get_messages().
23 You could however create a mail-object manually providing the
24 header and body each as either one string or as an array-ref
25 representing the lines.
26 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 use Mail::POP3Client;
32 use Mail::MboxParser::Mail;
33 my $pop = new Mail::POP3Client (...);
35 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 The above effectively behaves like an attachment-only retriever.
43 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 If a header-field occurs more than once in the header, the value of
50 the key is an array_ref. Example:
51 my $field = $msg->header->{field};
53 print $field->[0]; # first occurance of 'field'
54 print $field->[1]; # second one
55 ...
56 from_line
58 Returns the "From "-line of the message.
59 trace
61 This method returns the "Received: "-lines of the message as a
62 list.
63 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 Sets "$mail->error" if something went wrong.
72 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 $signature = $msg->body($msg->find_body)->signature;
80 Changes are good that find_body does what it is supposed to do.
82 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 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 get_field() always returns one string regardless of how many times
95 the field occured in the header. Multiple occurances are separated
96 by a newline and multiple whitespaces squeezed to one. That means
97 you can process each occurance of the field thusly:
98 for my $field ( split /\n/, $msg->get_field('received') ) {
100 # do something with $field
101 }
102 Sets "$mail->error" if the field was not found in which case
104 get_field() returns "undef".
105 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 print $mail->from->{email};
112 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 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 for my $recipient ($mail->to) {
121 print $recipient->{name} || "<no name>", "\n";
122 print $recipient->{email};
123 }
124 The same 'name'-smartness applies here as described under from().
126 cc Identical with to() but returning the hash-refed "Cc: "-line.
128 The same 'name'-smartness applies here as described under from().
130 id Returns the message-id of a message cutting off the leading and
132 trailing '<' and '>' respectively.
133 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 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 "$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 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 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 my $body = $mail->get_entity_body(0);
159 print FILEHANDLE $body;
160 and could be shortened to this:
162 $mail->store_entity_body(0, handle => \*FILEHANDLE);
164 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 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 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 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 Example:
210 $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 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 If 'path' does not exist, it will try to create the directory for
227 you.
228 You can specify to save only files matching a certain pattern. To
230 do that, use the store-only switch:
231 $msg->store_attachment(1, path => "/home/ethan/",
233 store_only => qr/\.jpg$/i);
234 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 store_only => '(?i)\.jpg$'
241 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 $msg->store_attachment(1, path => '/tmp', encode => 'utf-8');
251 See Encode::Supported for a list of encodings that you may use.
253 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 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 Returns a list of files that have been succesfully saved and an
267 empty list if no attachment could be extracted.
268 "$mail->error" will tell you possible failures and a possible
270 explanation for that.
271 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 my $mapping = $msg->get_attachments;
280 for my $filename (keys %$mapping) {
281 print "$filename => $mapping->{$filename}\n";
282 }
283 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 Even though it looks tempting, don't do the following:
290 # BAD!
292 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 The reason is that get_attachments() is currently not optimized to
299 cache the filename mapping. So, each time you call it on (even the
300 same) message, it will scan it from beginning to end. Better would
301 be:
302 # GOOD!
304 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 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 print $msg;
316 print $msg->as_string;
318
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 my $mb = Mail::MboxParser->new("/home/user/Mail/received");
326 for my $msg ($mb->get_messages) {
327 print $msg->effective_type, "\n";
328 }
329 effective_type() is not implemented by Mail::MboxParser::Mail and thus
331 the corresponding method of MIME::Entity is automatically called.
332 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
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
348 This is version 0.55.
349
351 Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>
352 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
358 MIME::Entity
359 Mail::MboxParser, Mail::MboxParser::Mail::Body,
361 Mail::MboxParser::Mail::Convertable
362perl v5.38.0 2023-07-20 MboxParser::Mail(3)