/ 
Email-Envelope-0.01
River stage zero No dependents
/ Email::Envelope

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.