MboxParser::Mail(3) User Contributed Perl Documentation MboxParser::Mail(3)NAMEMail::MboxParser::Mail - Provide mail-objects and methods upon
SYNOPSIS
See Mail::MboxParser for an outline on usage. Examples however are also
provided in this manpage further below.
DESCRIPTIONMail::MboxParser::Mail objects are usually not created directly though,
in theory, they could be. A description of the provided methods can be
found in Mail::MboxParser.
However, go on reading if you want to use methods from MIME::Entity and
learn about overloading.
METHODS
new(header, body)
This is usually not called directly but instead by
"get_messages()". You could however create a mail-object manually
providing the header and body each as either one string or as an
array-ref representing the lines.
Here is a common scenario: Retrieving mails from a remote POP-
server using Mail::POP3Client and directly feeding each mail to
"Mail::MboxParser::Mail->new":
use Mail::POP3Client;
use Mail::MboxParser::Mail;
my $pop = new Mail::POP3Client (...);
for my $i (1 .. $pop->Count) {
my $msg = Mail::MboxParser::Mail->new( [ $pop->Head($i) ],
[ $pop->Body($i) ] );
$msg->store_all_attachments( path => '/home/user/dump' );
}
The above effectively behaves like an attachment-only retriever.
header
Returns the mail-header as a hash-ref with header-fields as keys.
All keys are turned to lower-case, so $header{Subject} has to be
written as $header{subject}.
If a header-field occurs more than once in the header, the value of
the key is an array_ref. Example:
my $field = $msg->header->{field};
print $field->[0]; # first occurance of 'field'
print $field->[1]; # second one
...
from_line
Returns the "From "-line of the message.
trace
This method returns the "Received: "-lines of the message as a
list.
body
body(n)
Returns a Mail::MboxParser::Mail::Body object. For methods upon
that see further below. When called with the argument n, the n-th
body of the message is retrieved. That is, the body of the n-th
entity.
Sets "$mail->error" if something went wrong.
find_body
This will return an index number that represents what
Mail::MboxParser::Mail considers to be the actual (main)-body of an
email. This is useful if you don't know about the structure of a
message but want to retrieve the message's signature for instance:
$signature = $msg->body($msg->find_body)->signature;
Changes are good that find_body does what it is supposed to do.
make_convertable
Returns a Mail::MboxParser::Mail::Convertable object. For details
on what you can do with it, read
Mail::MboxParser::Mail::Convertable.
get_field(headerfield)
Returns the specified raw field from the message header, that is:
the fieldname is not stripped off nor is any decoding done. Returns
multiple lines as needed if the field is "Received" or another
multi-line field. Not case sensitive.
"get_field()" always returns one string regardless of how many
times the field occured in the header. Multiple occurances are
separated by a newline and multiple whitespaces squeezed to one.
That means you can process each occurance of the field thusly:
for my $field ( split /\n/, $msg->get_field('received') ) {
# do something with $field
}
Sets "$mail->error" if the field was not found in which case
"get_field()" returns "undef".
from
Returns a hash-ref with the two fields 'name' and 'email'. Returns
"undef" if empty. The name-field does not necessarily contain a
value either. Example:
print $mail->from->{email};
On behalf of suggestions I received from users, from() tries to be
smart when 'name'is empty and 'email' has the form
'first.name@host.com'. In this case, 'name' is set to "First Name".
to Returns an array of hash-references of all to-fields in the mail-
header. Fields are the same as those of "$mail->from". Example:
for my $recipient ($mail->to) {
print $recipient->{name} || "<no name>", "\n";
print $recipient->{email};
}
The same 'name'-smartness applies here as described under "from()".
cc Identical with to() but returning the hash-refed "Cc: "-line.
The same 'name'-smartness applies here as described under "from()".
id Returns the message-id of a message cutting off the leading and
trailing '<' and '>' respectively.
num_entities
Returns the number of MIME-entities. That is, the number of sub-
entitities actually. If 0 is returned and you think this is wrong,
check "$mail->log".
get_entities
get_entities(n)
Either returns an array of all MIME::Entity objects or one
particular if called with a number. If no entity whatsoever could
be found, an empty list is returned.
"$mail->log" instantly called after get_entities will give you some
information of what internally may have failed. If set, this will
be an error raised by MIME::Entity but you don't need to worry
about it at all. It's just for the record.
get_entity_body(n)
Returns the body of the n-th MIME::Entity as a single string, undef
otherwise in which case you could check "$mail->error".
store_entity_body(n, handle => FILEHANDLE)
Stores the stringified body of n-th entity to the specified
filehandle. That's basically the same as:
my $body = $mail->get_entity_body(0);
print FILEHANDLE $body;
and could be shortened to this:
$mail->store_entity_body(0, handle => \*FILEHANDLE);
It returns a true value on success and undef on failure. In this
case, examine the value of $mail->error since the entity you
specified with 'n' might not exist.
store_attachment(n)
store_attachment(n, options)
It is really just a call to store_entity_body but it will take care
that the n-th entity really is a saveable attachment. That is, it
wont save anything with a MIME-type of, say, text/html or so.
Unless further 'options' have been given, an attachment (if found)
is stored into the current directory under the recommended filename
given in the MIME-header. 'options' are specified in key/value
pairs:
key: | value: | description:
===========|================|===============================
path | relative or | directory to store attachment
(".") | absolute |
| path |
-----------|----------------|-------------------------------
encode | encoding | Some platforms store files
| suitable for | in e.g. UTF-8. Specify the
| Encode::encode | appropriate encoding here and
| | and the filename will be en-
| | coded accordingly.
-----------|----------------|-------------------------------
store_only | a compiled | store only files whose file
| regex-pattern | names match this pattern
-----------|----------------|-------------------------------
code | an anonym | first argument will be the
| subroutine | $msg-object, second one the
| | index-number of the current
| | MIME-part
| | should return a filename for
| | the attachment
-----------|----------------|-------------------------------
prefix | prefix for | all filenames are prefixed
| filenames | with this value
-----------|----------------|-------------------------------
args | additional | this array-ref will be passed
| arguments as | on to the 'code' subroutine
| array-ref | as a dereferenced array
Example:
$msg->store_attachment(1,
path => "/home/ethan/",
code => sub {
my ($msg, $n, @args) = @_;
return $msg->id."+$n";
},
args => [ "Foo", "Bar" ]);
This will save the attachment found in the second entity under the
name that consists of the message-ID and the appendix "+1" since
the above code works on the second entity (that is, with index =
1). 'args' isn't used in this example but should demonstrate how to
pass additional arguments. Inside the 'code' sub, @args equals
("Foo", "Bar").
If 'path' does not exist, it will try to create the directory for
you.
You can specify to save only files matching a certain pattern. To
do that, use the store-only switch:
$msg->store_attachment(1, path => "/home/ethan/",
store_only => qr/\.jpg$/i);
The above will only save files that end on '.jpg', not case-
sensitive. You could also use a non-compiled pattern if you want,
but that would make for instance case-insensitive matching a little
cumbersome:
store_only => '(?i)\.jpg$'
If you are working on a platform that requires a certain encoding
for filenames on disk, you can use the 'encode' option. This
becomes necessary for instance on Mac OS X which internally is
UTF-8 based. If the filename contains 8bit characters (like the
German umlauts or French accented characters as in 'e'), storing
the attachment under a non-encoded name will most likely fail. In
this case, use something like this:
$msg->store_attachment(1, path => '/tmp', encode => 'utf-8');
See Encode::Supported for a list of encodings that you may use.
Returns the filename under which the attachment has been saved.
undef is returned in case the entity did not contain a saveable
attachement, there was no such entity at all or there was something
wrong with the 'path' you specified. Check "$mail->error" to find
out which of these possibilities apply.
store_all_attachments
store_all_attachments(options)
Walks through an entire mail and stores all apparent attachments.
'options' are exactly the same as in "store_attachement()" with the
same behaviour if no options are given.
Returns a list of files that have been succesfully saved and an
empty list if no attachment could be extracted.
"$mail->error" will tell you possible failures and a possible
explanation for that.
get_attachments
get_attachments(file)
This method returns a mapping from attachment-names (if those are
savable) to index-numbers of the MIME-part that represents this
attachment. It returns a hash-reference, the file-names being the
key and the index the value:
my $mapping = $msg->get_attachments;
for my $filename (keys %$mapping) {
print "$filename => $mapping->{$filename}\n";
}
If called with a string as argument, it tries to look up this
filename. If it can't be found, undef is returned. In this case you
also should have an error-message patiently awaiting you in the
return value of "$mail->error".
Even though it looks tempting, don't do the following:
# BAD!
for my $file (qw/file1.ext file2.ext file3.ext file4.ext/) {
print "$file is in message ", $msg->id, "\n"
if defined $msg->get_attachments($file);
}
The reason is that "get_attachments()" is currently not optimized
to cache the filename mapping. So, each time you call it on (even
the same) message, it will scan it from beginning to end. Better
would be:
# GOOD!
my $mapping = $msg->get_attachments;
for my $file (qw/file1.ext file2.ext file3.ext file4.ext/) {
print "$file is in message ", $msg->id, "\n"
if exists $mapping->{$file};
}
as_string
Returns the message as one string. This is the method that string
overloading depends on, so these two are the same:
print $msg;
print $msg->as_string;
EXTERNAL METHODSMail::MboxParser::Mail implements an autoloader that will do the
appropriate type-casts for you if you invoke methods from external
modules. This, however, currently only works with MIME::Entity. Support
for other modules will follow. Example:
my $mb = Mail::MboxParser->new("/home/user/Mail/received");
for my $msg ($mb->get_messages) {
print $msg->effective_type, "\n";
}
"effective_type()" is not implemented by Mail::MboxParser::Mail and
thus the corresponding method of MIME::Entity is automatically called.
To learn about what methods might be useful for you, you should read
the "Access"-part of the section "PUBLIC INTERFACE" in the MIME::Entity
manpage. It may become handy if you have mails with a lot of MIME-
parts and you not just want to handle binary-attachments but any kind
of MIME-data.
OVERLOADINGMail::MboxParser::Mail overloads the " " operator. Overloading
operators is a fancy feature of Perl and some other languages (C++ for
instance) which will change the behaviour of an object when one of
those overloaded operators is applied onto it. Here you get the
stringified mail when you write $mail while otherwise you'd get the
stringified reference: "Mail::MboxParser::Mail=HASH(...)".
VERSION
This is version 0.55.
AUTHOR AND COPYRIGHT
Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>
Copyright (c) 2001-2005 Tassilo von Parseval. This program is free
software; you can redistribute it and/or modify it under the same terms
as Perl itself.
SEE ALSO
MIME::Entity
Mail::MboxParser, Mail::MboxParser::Mail::Body,
Mail::MboxParser::Mail::Convertable
perl v5.14.1 2005-12-08 MboxParser::Mail(3)
