/ 
E-Mail-Acme-822
River stage zero No dependents
/ E'Mail::Acme

NAME

E'Mail::Acme - the epitome of simple e-mail handling

VERSION

version 822

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.