MboxParser::Mail(3pm)					User Contributed Perl Documentation				     MboxParser::Mail(3pm)

NAME

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

DESCRIPTION

       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.

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 /
/, $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>", "
";
			   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 successfully 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 saveable) 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}
";
	       }

	   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, "
"
		       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, "
"
		       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 METHODS

       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, "
";
	       }

       "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.

OVERLOADING

       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(...)".

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.12.3							    2011-06-25						     MboxParser::Mail(3pm)