NAME

Email::Envelope - Email with SMTP time information

SYNOPSIS

 use Email::Envelope;
 my $mailenv = Email::Envelope->new();
 $mailenv->remote_host('mx.example.com');
 ...

OR

 my $mailenv = Email::Envelope->new({
    remote_port => 29,
    secure => 1,
    ...
 });

DESCRIPTION

This module has been designed as a simple container with a few handy methods. Currently Email::Simple contains RFC2822 data, however when dealing with filtering Email, sometimes the information available just isn't enough. Many people may wish to block certain subnets or run SBL/XBL checks. This module has been provided for this very reason.

METHODS

new

Currently the constructor supports adding data via hash references for the following data:

 remote_host
 remote_port
 local_host
 local_port
 secure
 rcpt_to
 mail_from
 helo
 data
 mta_msg_id
 received_timestamp

And can be used as so:

 my $mailenv = Email::Envelope->new({
   remote_host => '127.0.0.1',
   local_host => 'mx.example.com',
   ...
 });

remote_host

Simple accessor. Will only accept either an IP address or a Fully Qualified Domain Name. Will die upon wrong value being set.

 $mailenv->remote_host('127.0.0.1');
 print $mailenv->remote_host;

 $mailenv->remote_host('mx.example.com');
 print $mailenv->remote_host;

remote_port

Simple accessor. Will only accept a positive integer. Will die upon wrong value being set.

 $mailenv->remote_port(25);
 print $mailenv->remote_port;

local_host

Simple accessor. Will only accept either an IP address or a Fully Qualified Domain Name. Will die upon wrong value being set.

 $mailenv->local_host('127.0.0.1');
 print $mailenv->local_host;

 $mailenv->local_host('mx.example.com');
 print $mailenv->local_host;

local_port

Simple accessor. Will only accept a positive integer. Will die upon wrong value being set.

 $mailenv->local_port(25);
 print $mailenv->local_port;

secure

Simple accessor. Requires either a 'true' or 'false' value.

 $mailenv->secure(1);
 $mailenv->secure(0);
 print "Secured" if $mailenv->secure;

mta_msg_id

Simple accessor/mutator. Will take an arbitary string representing the message ID that the MTA has assigned.

 $mailenv->mta_msg_id("Exim-2004/22927437493-189282");
 print "MTA reports this message as " . $mailenv->mta_msg_id;

recieved_timestamp

Simple accessor/mutator. Will take a unix epoch to represent the time that the message arrived with the MTA.

 $mailenv->recieved_timestamp(103838934);
 my $dt = Date::Time->new($mailenv->recieved_timestamp);

rcpt_to

Simple Accessor.

 $mailenv->rcpt_to("Example User <user\@example.com>");
 print $mailenv->rcpt_to;

 $mailenv->rcpt_to("Example User <user\@example.com>, Another User <another\@example.com>");
 print $mailenv->rcpt_to;

mail_from

Simple Accessor.

 $mailenv->mail_from("Example User <user\@example.com>");
 print $mailenv->mail_from;

helo

Simple Accessor.

 $mailenv->helo("HELO mx.example.com");
 print $mailenv->helo;

data

Simple accessor. Uses an Email::Simple object internally.

 $mailenv->data($rfc2822);
 print $mailenv->data;

simple

Simple getter. Will return an Email::Simple object based on the DATA that the current object contains.

 my $simple = $mailenv->simple;

to_address

Simple getter. Will return an Email::Address object based on the RCPT_TO address that the current object contains.

 my $address   = $mailenv->to_address;
 my @addresses = $mailenv->to_address;

NB: in scalar context to_address() will return the first address in the list.

from_address

Simple getter. Will return an Email::Address object based on the MAIL_FROM address that the current object contains.

 my $address = $mailenv->from_address;

NB: Since RFC 2821 states that there can only be one MAIL_FROM address per smtp session, if you supply more than one MAIL_FROM format to mail_from() then you will only recieve back the first address in the list.

COVERAGE

This module has been written using test-first development. Below are the Devel::Cover details.

 ---------------------------- ------ ------ ------ ------ ------ ------ ------
 File                           stmt branch   cond    sub    pod   time  total
 ---------------------------- ------ ------ ------ ------ ------ ------ ------
 blib/lib/Email/Envelope.pm    100.0   90.5  100.0  100.0  100.0  100.0   97.8
 Total                         100.0   90.5  100.0  100.0  100.0  100.0   97.8
 ---------------------------- ------ ------ ------ ------ ------ ------ ------

HISTORY

0.01

Initial release to CPAN.

0.00_02

Fixes to how Email::Address is used. Added mta_msg_id and received_timestamp.

0.00_01

Initial implementation.

TODO

IPv6 support

SEE ALSO

Email::Simple Email::Address

AUTHOR

Scott McWhirter <kungfuftr@cpan.org>

SUPPORT

This module is part of the Perl Email Project - http://pep.kwiki.org/

There is a mailing list at pep@perl.org (subscribe at pep-subscribe@perl.org) and an archive available at http://nntp.perl.org/group/pep.php

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Scott McWhirter

This library is released under a BSD licence, please see http://www.opensource.org/licenses/bsd-license.php for more information.

cpanm Email::Envelope

perl -MCPAN -e shell
install Email::Envelope