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

FreeBSD Manual Pages

  
 
  

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

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 /\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 '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.

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

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

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

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

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

NAME | SYNOPSIS | DESCRIPTION | METHODS | EXTERNAL METHODS | OVERLOADING | VERSION | AUTHOR AND COPYRIGHT | SEE ALSO | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::MboxParser::Mail&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help