Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MboxParser::Mail(3)   User Contributed Perl Documentation  MboxParser::Mail(3)

       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.

       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

	       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.

	   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

	   Returns the "From "-line of the message.

	   This	method returns the "Received: "-lines of the message as	a

	   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

	   Sets	"$mail->error" if something went wrong.

	   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.

	   Returns a Mail::MboxParser::Mail::Convertable object. For details
	   on what you can do with it, read

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

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

       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.

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

	   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.

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

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

	       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 'A(C)'), 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.

	   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.

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

	   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,

       Hey! The	above document had some	coding errors, which are explained

       Around line 683:
	   Non-ASCII character seen before =encoding in	''A(C)'),'. Assuming

perl v5.24.1			  2005-12-08		   MboxParser::Mail(3)


Want to link to this manual page? Use this URL:

home | help