NAME
E'Mail::Acme - the epitome of simple e-mail handling
VERSION
version 1123
SYNOPSIS
my $e_mail = E'Mail::Acme;
$e_mail->{From} = q<Ricardo SIGNES <rjbs@acme.example.biz>>;
$e_mail->{To } = q<Alvin Theodore <monk@chip.shoulder.dw>>;
$e_mail->{Subject} = 'Finally, a simple e-mail module!';
push @$e_mail,
'Alvin,',
'',
'I agree! What the world needs is a module that makes e-mail more',
'accessible to the common man -- or at least the common Perl programmer.',
'',
'I have attached a modest example.',
;
$e_mail->('sendmail');
DESCRIPTION
Good grief, everywhere you turn there's yet another e-mail module! This
one says that the message is an object. That one says that every *field*
is an object. Then there's the one that says the darn body is an object!
How many methods do I need to learn, anyway? Look, an e-mail is simple.
It's a set of name/value pairs forming a header and a list of lines.
That's it! Anybody who tells you otherwise is just being a nervous
Nelly.
E'Mail::Acme is the epitome of simple e-mail handling. It does use an
object, but only to help produce a synergistic, cohesive unity of
purpose. It uses *just* the familiar, existing Perl data system so that
you only need use the Perl you already know -- none of this overwrought
API that we've all gotten so sick of.
METHODS
None.
CONSTRUCTION
Making a new e-mail is easy:
my $e_mail = E'Mail::Acme;
HEADERS
Setting headers is easy:
$e_mail->{header} = "First Value";
$e_mail->{HeadEr} = "Second Value";
print $e_mail->{header};
# header: First Value
# HeadeR: Second Value
You can also assign multiple values at once:
$e_mail->{XForce} = [ qw(Lethal Aggressive) ];
print $e_mail->{XForce};
# X-Force: Lethal
# X-Force: Aggressive
To clear all of those headers, you can just:
delete $e_mail->{xforce};
Or, to delete just the first, either of these will work:
delete $e_mail->{XForce}[0];
splice @{ $e_mail->{XForce} }, 0, 1;
Alternately, more values could be added in a similar fashion:
push @{ $e_mail->{XForce} }, 'except on Sundays';
splice @{ $e_mail->{XForce} }, 1, 0, 'and';
Of course, individual header values can be passed around and used to
affect the original message:
my $recipients = $e_mail->{to};
munge_values($recipients); # the $e_mail is altered
This frees you from passing around a large clunky message "object" when
you only need to deal with part of it.
THE BODY
The body is just a sequence of lines, and you can treat it as such:
@$e_mail = "Friends, Romans, Countrymen:"
, ''
, 'Lend me your ears!';
You can always easily add your sig to a message:
my $sig = "-- \nrjbs\n";
push @$e_mail, $sig;
E'Mail::Acme will take care of all the conversion of newlines, breaking
up text on all likely newlines and normalizing to CRLF.
MULTIPART
Multipart messages are easy: just push more e-mails onto the body.
my $e_mail = E'Mail::Acme; # top part;
my $part_1 = E'Mail::Acme; # attachment
my $part_2 = E'Mail::Acme; # attachment
push @$e_mail, $part_1, $part_2;
Any lines in a multi-part e-mail message form the preamble, and an
arrayref of subparts is always available at the end of the e-mail --
that is, like this:
my $subparts = $e_mail->[ scalar @$e_mail ];
Nested multipart messages are handled just fine. A multipart
content-type will be added, if none has been supplied. If a multipart
content-type is set, but the boundary is not, it will be added. Do not
set your own boundary unless you know what you are doing! You will
probably produce a corrupt message!
SENDING MAIL
A mail exists to be sent, not hoarded! Once you've composed your e-mail
message, you can send it just how you'd expect:
$e_mail->();
If your sendmail program is not installed in your path, you can specify
which program to use by passing it as an argument:
$e_mail->(q(c:/program files/sendmail/sendmail.exe));
THANKS
Thanks to Simon, Simon, Casey, Richard, Dave, Dieter, Meng, Mark,
Graham, Tim, Yves, David, Eryq and everyone else who has helped form my
understand of how e-mail should be handled.
AUTHOR
Ricardo SIGNES wrote this module on Friday, July 13, 2007.
COPYRIGHT AND LICENSE
This code is copyright (c) 2007, Ricardo SIGNES. It is free software,
available under the same terms as Perl itself.