NAME
Mail::Sender::Easy - Super Easy to use simplified interface to Mail::Sender's excellentness
SYNOPSIS
use Mail::Sender::Easy qw(email);
email({
%mail_sender_config,
_text => 'Hello World',
}) or die "email() failed: $@";DESCRIPTION
Easy "email() or die $@" interface to Mail::Sender.
See "EXTENDED DESCRIPTION" and "DISCUSSION OF THE NAMESPACE" for more info.
Also adds more detailed info to the X-Mailer header to track usage.
Function: email()
email(\%email) or die "Email error: $@";
if(email(\%email)) {
log_sent_emails(\%email);
print "Your email has been sent!\n";
}
else {
log_failed_email($@, \%email);
print "Sorry, I could not send your email!\n";
}Method: $sender->easy()
Same hashref as email() but called with a Mail::Sender object you created previously:
my $sender = Mail::Sender->new();
$sender->easy(\%email) or die "Email error: $@";
The keys to this hash are the keys described in Mail::Sender's docs in the "Parameters" Section with the addition of 3 new ones:
_text
The value is the text/plain part of the message, its the only required one.
_html
The value is the text/html part of the message, it is not required.
_text_info
Value is a hashref of additonal args to Mail::Sender->Part() for text in text and html emails, Mail::Sender->Body() in text with attachement. ctype, disposition, msg are ignored since they are set by other means.
The perfect place to set 'encoding' and 'charset'
_html_info
Value is a hashref of additonal args to Mail::Sender->Part() for html. ctype, disposition, msg are ignored since they are set by other means.
The perfect place to set 'encoding' and 'charset'
_attachments
Encoding of attachments is always Base64. The value of this key is a hash reference.
In that hashref each key is a filename, not the entire path, just the filename, to be attached. The value is another hashref described below. (Don't panic, its not as complex as it sounds at this point, see the EXAMPLE to see what I mean.)
_attachments => { 'file.name' => { this hash is described here }, }
You *must* specify the "file" key or the "msg" key, the "msg" key takes precedence.
The keys are:
- file
-
Path to the file to attach.
'file' => '/home/foo/docs/fiddle.txt',Makes the attachment via Mail::Sender::Attach()
- msg
-
Contents of the file (instead of using a path)
'msg' => $fiddle_txt_content,Makes the attachment via Mail::Sender::Part()
- ctype
-
Content type of the attachement
'ctype' => 'image/png',Mail::Sender will guess if not specified but its a good idea to specify it.
Defaults to text/plain
- description
-
Short textual description or title of this file:
'description' => 'Fiddle Info',Defaults to the filename you used for this hashref's key (IE "file.name" from the "this hash described here" header).
- _disptype
-
Short textual description of the type of file:
'_disptype' => 'Text Document',Defaults to the filename you used for this hashref's key (IE "file.name" from the "this hash described here" header).
- _inline
-
The value is used as its "cid" and makes it attached inline
'_inline' => 'fiddlepic1',in the html section:
<img src="cid:fiddlepic1" />If not specified its not "inline", its just attached :)
The _disptype and _inline are used to build the actual "dispositon" part which is described in Mial::Sender's docs if you want to know the nitty gritty.
EXPORT
None by default. email() is exportable
EXAMPLE
Send an email via SMTP with authentication, on an alternate port, a plain text part, html part that has an inline smiley image, a PDF attachment, a high priority and read and delivery receipt request:
use Mail::Sender::Easy qw(email);
email({
'from' => 'foo@bar.baz',
'to' => 'you@ddre.ss',
'cc' => 'your_pal@ddre.ss',
'subject' => 'Perl is great!',
'priority' => 2, # 1-5 high to low
'confirm' => 'delivery, reading',
'smtp' => '1.2.3.4',
'port' => 26,
'auth' => 'LOGIN',
'authid' => 'foo@bar.baz',
'authpwd' => 'protect_with_700_perms_or_get_it_from_input',
'_text' => 'Hello *World* :)',
'_html' => 'Hello <b>World</b> <img src="cid:smile1" />',
'_attachments' => {
'smiley.gif' => {
'_disptype' => 'GIF Image',
'_inline' => 'smile1',
'description' => 'Smiley',
'ctype' => 'image/gif',
'file' => '/home/foo/images/smiley.gif',
},
'mydata.pdf' => {
'description' => 'Data Sheet',
'ctype' => 'application/pdf',
'msg' => $pdf_guts,
},
},
}) or die "email() failed: $@";EXTENDED DESCRIPTION
Mail::Sender is a great module. I have great respect for Jenda as you can tell from the list archives :)
Mail::Sender's one problem is its a bit cumbersome to use, with so many options and things to open, close, the whole thing, parts, multiparts etc etc., and several ways to check for successs. Its hard to remember what needs done at what point with what data to do what you want and then which way you check what data based on what was done to see if it worked or not.
This module's aim is to make all of that ``Easy'', Simple, User Friendly, etc etc (see "DISCUSSION OF THE NAMESPACE" below)
It does so by providing a single function (and method) to send mail based on an (IMHO) easier to work with hashref and returns true or false on success or failer and sets $@ to any errors.
The EXAMPLE section shows an ``email or die'' that will send an email using SMTP Auth on port 26 with text and html parts, the html part has a smiley gif embedded inline and a PDF attached and a high priority flag and read and delivery receipt requests. It will take you seconds to customize it to send that to yourself (and its ``Easy'' to understand what its going on without having to understand the intracacies of SMTP and MIME messages. Now try it with plain the Mail::Sender manpage. See? Much much ``Easy''ier to do, understand, troubelshoot, maintain, etc etc :)
DISCUSSION OF THE NAMESPACE
When first registering this name space I was told Easy and Simple are bad name spaces, but Simple did seem to describe it in the spirit of LWP::Simple (I'd missed Adam's response for some reason...)
http://www.xray.mpe.mpg.de/mailing-lists/modules/2005-12/msg00270.html
And then starting in January:
http://www.xray.mpe.mpg.de/mailing-lists/modules/2006-01/msg00008.html
So I registered "Simple" but was told that was still not going to fly despite the "LWP::Simple" in the previous thread.
http://www.xray.mpe.mpg.de/mailing-lists/modules/2006-01/msg00016.html
After receiveing no further recommendation of a registerable NS as requested I attempted "Friendly" with a request that if that was no good to please recommend something that is proper and was met with stone cold silence as of this rant being typed Sat Jan 7 16:24:28 CST 2006.
http://www.xray.mpe.mpg.de/mailing-lists/modules/2006-01/msg00044.html
So with no other option I decided to go with Easy (unregistered as recommended in one of the threads above) because:
- Its short
- Its more accurate and descriptive than Simple even though it may not be perfect (and since no others were suggested)
-
"Simple" could mean easy to use, simple messages, not very intelligent, etc
- I could not think of an alternative that was more accurate
- No one gave me any alternative "valid" options
-
I asked for one but only got ""Easy" isn't good"
I tried ;p
- It was already done, so I didn't have to change the code
So with all that in mind I'd like to put here an:
Open ended request to modules@perl.org
I'd like to request that either this name space be registered under my account or you suggest a name space that will be "registerable" and is short and descriptive of the module.
Thanks!
SEE ALSO
AUTHOR
Daniel Muey, http://drmuey.com/cpan_contact.pl
COPYRIGHT AND LICENSE
Copyright 2005 by Daniel Muey
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.