######################################################################
Mail::DWIM 0.04
######################################################################
NAME
Mail::DWIM - Do-What-I-Mean Mailer
SYNOPSIS
use Mail::DWIM qw(mail);
mail(
to => 'foo@bar.com',
subject => 'test message',
text => 'test message text'
);
DESCRIPTION
"Mail::DWIM" makes it easy to send email. You just name the recipient,
the subject line and the mail text and Mail::DWIM does the rest.
This module isn't for processing massive amounts of email. It is for
sending casual emails without worrying about technical details.
"Mail::DWIM" lets you store commonly used settings (like the default
sender email address or the transport mechanism) in a local
configuration file, so that you don't have to repeat settings in your
program code every time you want to send out an email. You are certainly
free to override the default settings if required.
"Mail::DWIM" uses defaults wherever possible. So if you say
use Mail::DWIM qw(mail);
mail(
to => 'foo@bar.com',
subject => 'test message',
text => 'test message text',
);
that's enough for the mailer to send out an email to the specified
address. There's no "from" field, so "Mail::DWIM" uses 'user@domain.com'
where "user" is the current Unix user and "domain.com" is the domain set
in the Perl configuration ("Config.pm"). If you want to specify a
different 'From:' field, go ahead:
mail(
from => 'me@mydomain.com',
to => 'foo@bar.com',
subject => 'test message',
text => 'test message text',
);
By default, "Mail::DWIM" connects to a running sendmail daemon to
deliver the mail. But you can also specify an SMTP server:
mail(
to => 'foo@bar.com',
subject => 'test message',
text => 'test message text',
transport => 'smtp',
smtp_server => 'smtp.foobar.com',
);
Or, if you prefer that Mail::DWIM uses the "mail" Unix command line
utility, use 'mail' as a transport:
mail(
to => 'foo@bar.com',
subject => 'test message',
text => 'test message text',
transport => 'mail',
program => '/usr/bin/mail',
);
On a given system, these settings need to be specified only once and put
into a configuration file. All "Mail::DWIM" instances running on this
system will pick them up as default settings.
Configuration files
There is a global "Mail::DWIM" configuration file in "/etc/maildwim"
with global settings and a user-specific file in "~user/.maildwim" which
overrides global settings. Both files are optional, and their format is
YAML:
# ~user/.maildwim
from: me@mydomain.com
reply-to: me@mydomain.com
transport: sendmail
Error Handling
By default, "Mail::DWIM" throws an error if something goes wrong (aka:
it dies). If that's not desirable and you want it to return a true/false
value code instead, set the "raise_error" option to a false value:
my $rc = mail(
raise_error => 0,
to => 'foo@bar.com',
...
);
if(! $rc) {
die "Release the hounds: ", Mail::DWIM::error();
}
The detailed error message is available by calling Mail::DWIM::error().
Attaching files
If you want to include an image, a PDF files or some other attachment in
an email, use the "attach" parameter
mail(
to => 'foo@bar.com',
subject => 'Pics of my new dog',
attach => ['doggie1.jpg', 'doggie2.jpg'],
text => "Hey, here's two cute pictures of Fritz :)",
);
Sending HTML Emails
Many people hate HTML emails, but if you also attach a plaintext version
for people with arcane email readers, everybody is happy. "Mail::DWIM"
makes this easy with the "html_compat" option:
mail(
to => 'foo@bar.com',
subject => 'test message',
html_compat => 1,
text => 'This is an HTML email.'
);
This will create two attachments, the first one as plain text (generated
by HTML::Text to the best of its abilities), followed by the specified
HTML message marked as content-type "text/html". Non-HTML mail readers
will pick up the first one, and Outlook-using marketroids get fancy
HTML. Everytext wins.
Test Mode
If the environment variable "MAIL_DWIM_TEST" is set to a filename,
"Mail::DWIM" prepares mail as usual, but doesn't send it off using the
specified transport mechanism. Instead, it appends outgoing mail ot the
specified file.
"Mail::DWIM"'s test suite uses this mode to run a regression test
without needing an MTA.
Why another Mail Module?
The problem with other Mail:: or Email:: modules on CPAN is that they
expose more options than the casual user needs. Why create a mailer
object, call its accessors and then its "send" method if all I want to
do is call a function that works similarily to the Unix "mail" program?
"Mail::DWIM" tries to be as 'Do-What-I-mean' as the venerable Unix
"mail" command. Noboby has to read its documentation to use it:
$ mail m@perlmeister.com
Subject: foobar
quack! quack!
.
Cc:
CTRL-D
LEGALESE
Copyright 2007 by Mike Schilli, all rights reserved. This program is
free software, you can redistribute it and/or modify it under the same
terms as Perl itself.
AUTHOR
2007, Mike Schilli