NAME

Mail::Action::Request - base for building modules that represent incoming mail

SYNOPSIS

use base 'Mail::Action::Request';

DESCRIPTION

METHODS

Mail::Action::Request objects have the following methods in several categories:

Creation and Initialization

new()

init()

Accessors

message()

Returns the raw Email::Simple object representing the incoming message.

headers()

Returns a hash reference of known message headers and their values. This can be dangerous, so use it cautiously.

header( $name )

If the invocant has a header of the given $name, returns the first or all of the values associated with that header, depending on the context of the call. This will return nothing if the named header does not exist.

key( [ $new_key ] )

Returns the key associated with this request, if it exists. (The key of a request is usually, but not always, the extension of an extended e-mail address: extension in <you+extension@example.com<, for example.)

You can use this to store a key, if you must.

recipient( [ $new_recipient ] )

Returns the e-mail address for which this request exists. It is difficult to determine this reliably and generically across a whole swath of mail servers, but this makes its best guess. Note that this will contain the key, if it exists.

You can use this to store a recipient, if you must.

recipient_header( [ $new_recipient_header ] )

Returns the name of the header from which the recipient address came. You'll almost never need this, but when you do need it, you'll really need it.

You can use this to store a recipient header, if absolutely necessary.

recipient_headers()

Depending on your mail server, you may need to override this in your own applications to provide a list of headers to check for the e-mail address to which the server delivered a message. With Postfix, at least, it appears that the Delivered-To header is always correct. This will fall back to To and Cc as next-best guesses.

Ideally, there will be roles to apply for your mail server of choice that handle this for you automatically.

store_header( $name, $value )

Given the $name of a header and an array reference in $value, representing the value of that header, stores both in the invocant's headers structure.

Other Methods

If you want to subclass this, you might care about the methods:

add_headers()

Adds the Subject and address headers to the object.

find_headers( [ @list_of_headers ] )

Attempts to find every header in the argument list in the message. Adds every header found to the list of known headers in the object.

find_address_headers()

Adds all recipient headers (see recipient_headers()) and the From header to the object.

add_recipient()

Attempts to set the recipient for this request, if there's not one set already. Otherwise, it checks all of the headers from recipient_headers(), in order, trying to find a likely recipient.

remove_recipient( $recipient_header, $recipient )

Removes the $recipient from the $recipient_header, leaving the rest of the message headers undisturbed. The idea here is to figure out which address received this message, avoid sending the mail to that address again, and pass it on appropriately otherwise.

find_key()

Attempts to find and set the key for this request. The key is the portion of the recipient address immediately following the + sign before the domain name. That is, for tempmail+fun_list@example.com the key is fun_list. Override this if you have a different way to mark keys.

process_body( $address )

Given the equivalent of an Mail::Action::Address object, removes the signature of the message, removes and processes all of the directives from the body(using the $address), and returns a reference to an array containing the remaining lines of the body.

remove_sig()

Attempts to remove the signature from the message by removing everything following a line containing -- . This returns a reference to an array containing the remaining lines.

It tries to do the right thing with multipart messages, but it looks only in the first part for the signature. This may or may not be correct, depending on how broken the sending MUA was.

copy_headers()

Copies all headers from the incoming message to a hash reference where the key is the name of the header and the value is a comma-separated list of values for the header. This explicitly removes the From header that sometimes procmail seems to add in some cases.

SEE ALSO

Mail::SimpleList and Mail::TempAddress for example uses.

See Mail::Action::Storage, Mail::Action::Address, and Mail::Action::PodToHelp for related modules.

AUTHOR

chromatic, chromatic at wgz dot org.

BUGS

No known bugs.

COPYRIGHT

Copyright (c) 2003 - 2009 chromatic. Some rights reserved. You may use, modify, and distribute this module under the same terms as Perl 5.10 itself.