NAME

Mail::SpamAssassin::Message - decode, render, and hold an RFC-2822 message

DESCRIPTION

This module encapsulates an email message and allows access to the various MIME message parts and message metadata.

The message structure, after initiating a parse() cycle, looks like this:

  Message object, also top-level node in Message::Node tree
     |
     +---> Message::Node for other parts in MIME structure
     |       |---> [ more Message::Node parts ... ]
     |       [ others ... ]
     |
     +---> Message::Metadata object to hold metadata

PUBLIC METHODS

new()

Creates a Mail::SpamAssassin::Message object. Takes a hash reference as a parameter. The used hash key/value pairs are as follows:

message is either undef (which will use STDIN), a scalar of the entire message, an array reference of the message with 1 line per array element, or a file glob which holds the entire contents of the message.

Note: The message is expected to generally be in RFC 2822 format, optionally including an mbox message separator line (the "From " line) as the first line.

parse_now specifies whether or not to create the MIME tree at object-creation time or later as necessary.

The parse_now option, by default, is set to false (0). This allows SpamAssassin to not have to generate the tree of Mail::SpamAssassin::Message::Node objects and their related data if the tree is not going to be used. This is handy, for instance, when running spamassassin -d, which only needs the pristine header and body which is always handled when the object is created.

subparse specifies how many MIME recursion levels should be parsed. Defaults to 20.

_do_parse()

Non-Public function which will initiate a MIME part parse (generates a tree) of the current message. Typically called by find_parts() as necessary.

find_parts()

Used to search the tree for specific MIME parts. See Mail::SpamAssassin::Message::Node for more details.

get_pristine_header()

Returns pristine headers of the message. If no specific header name is given as a parameter (case-insensitive), then all headers will be returned as a scalar, including the blank line at the end of the headers.

If called in an array context, an array will be returned with each specific header in a different element. In a scalar context, the last specific header is returned.

ie: If 'Subject' is specified as the header, and there are 2 Subject headers in a message, the last/bottom one in the message is returned in scalar context or both are returned in array context.

Note: the returned header will include the ending newline and any embedded whitespace folding.

get_mbox_separator()

Returns the mbox separator found in the message, or undef if there wasn't one.

get_body()

Returns an array of the pristine message body, one line per array element.

get_pristine()

Returns a scalar of the entire pristine message.

get_pristine_body()

Returns a scalar of the pristine message body.

extract_message_metadata($main)

$str = get_metadata($hdr)

put_metadata($hdr, $text)

delete_metadata($hdr)

$str = get_all_metadata()

finish_metadata()

Destroys the metadata for this message. Once a message has been scanned fully, the metadata is no longer required. Destroying this will free up some memory.

finish()

Clean up an object so that it can be destroyed.

receive_date()

Return a time_t value with the received date of the current message, or current time if received time couldn't be determined.

PARSING METHODS, NON-PUBLIC

These methods take a RFC2822-esque formatted message and create a tree with all of the MIME body parts included. Those parts will be decoded as necessary, and text/html parts will be rendered into a standard text format, suitable for use in SpamAssassin.

parse_body()

parse_body() passes the body part that was passed in onto the correct part parser, either _parse_multipart() for multipart/* parts, or _parse_normal() for everything else. Multipart sections become the root of sub-trees, while everything else becomes a leaf in the tree.

For multipart messages, the first call to parse_body() doesn't create a new sub-tree and just uses the parent node to contain children. All other calls to parse_body() will cause a new sub-tree root to be created and children will exist underneath that root. (this is just so the tree doesn't have a root node which points at the actual root node ...)

_parse_multipart()

Generate a root node, and for each child part call parse_body() to generate the tree.

_parse_normal()

Generate a leaf node and add it to the parent.