Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  MAIL::MBOXPARSER::MAIL (3)

.ds Aq ’


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



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


Mail::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.


<B>new(header, body)B> 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.

<B>headerB> 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

<B>from_lineB> Returns the From -line of the message.
<B>traceB> This method returns the Received: -lines of the message as a list.
<B>body(n)B> 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.

<B>find_bodyB> 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.

<B>make_convertableB> Returns a Mail::MboxParser::Mail::Convertable object. For details on what you can do with it, read Mail::MboxParser::Mail::Convertable.
<B>get_field(headerfield)B> 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.

<B>fromB> 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 ’’. In this case, ’name’ is set to First Name.

<B>toB> 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().

<B>ccB> Identical with to() but returning the hash-refed Cc: -line.

The same ’name’-smartness applies here as described under from().

<B>idB> Returns the message-id of a message cutting off the leading and trailing ’<’ and ’>’ respectively.
<B>num_entitiesB> 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.
<B>get_entities(n)B> 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.

<B>get_entity_body(n)B> Returns the body of the n-th MIME::Entity as a single string, undef otherwise in which case you could check $mail->error.
<B>store_entity_body(n, handle => FILEHANDLE)B> 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.

<B>store_attachment(n, options)B> 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


                            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\k:'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.

<B>store_all_attachments(options)B> 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.

<B>get_attachments(file)B> 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 <B>notB> 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};

<B>as_stringB> 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;


Mail::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.


Mail::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(...).


This is version 0.55.


Tassilo von Parseval <>

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.



Mail::MboxParser, Mail::MboxParser::Mail::Body, Mail::MboxParser::Mail::Convertable


Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 683: Non-ASCII character seen before =encoding in ’’e\k:'Assuming ISO8859-1
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 MBOXPARSER::MAIL (3) 2005-12-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.