HTML::Mail - Perl extension for sending emails with embedded HTML and media
use HTML::Mail; ### initialisation my $html_mail = HTML::Mail->new( HTML => 'http://www.cpan.org', Text => 'This is the text representation of the webpage http://www.cpan.org', From => 'me@myhost.org', To => 'you@yourhost.org', Subject => 'CPAN webpage'); ### Send the email ("inherited" from MIME::Lite) $html_mail->send(); #### Remove text representation $html_mail->set_Text(); ### Rebuild the message and send $html_mail->build->send; ### Serialise to file for later reuse $html_mail->dump_file('/tmp/cpan_mail.data'); ### Restore from file my $restored = HTML::Mail->restore_file('/tmp/cpan_mail.data');
HTML::Mime is supposed to help with the task of sending emails with HTML and images (or other media) embedded . It uses MIME::Lite for all MIME related jobs, HTML::Parser to find related files and change the URIs and LWP::UserAgent to retrieve the related files.
Email can be 'multipart/alternative' if both HTML and Text content exist and 'multipart/related' if there is only HTML content.
If you want to send text-only email, you probably won't find this module usefull at all.
Constructor. Initialises the object. See the attributes section
Regenerates the email. Allows you to change any attributes as in the constructor. Main difference with new is that it doesn't fetch content that was previously fetched/parsed.
new
Returns the LWP::UserAgent object used internally so that it can the customised
Serialises the object to a string
Serialises the object to a file
Restores previously serialised object
Restores previously serialised object from a file
All attributes are case sensitive.
my $html_mail = HTML::Mail->new(attribute => value); $html_mail->build(attribute => value);
Constructor supports these attributes:
The URL of HTML data to send in email. Most common URLs are either http://www.site.org or file:///home/user/page.html
If you prefer, you can use it to specify the actual HTML data as a string
HTML=>'<html><body><h1>Welcome to HTML::Mail</h1></body></html>';
The URL of Text data to send in email. Similar to the HTML attribute.
Inherited from MIME::Lite. Sender, Recipient and Subject of the message.
Charset of the HTML part of the email. Defaults to iso-8859-15.
Charset of the text part of the email. Defaults to iso-8859-15.
LWP::UserAgent object used to retrieve documents. The default agent has a 60 second timeout and sends HTML::Mail as the agent. See also ADVANCED USAGE.
A true value specifies that when the HTML uses external css this content be placed in the <style> tag at the header of the document, default value is true.
Don't change the default behaviour unless there is a very strong reason since most email clients won't interpret css unless they are in-lined.
Controls which links are also included in the email. See Linked Media.
The lwp_ua method returns the instance of LWP::UserAgent used to make the request. Using this method you can change it's options to your needs.
lwp_ua
my $ua = LWP::UserAgent->new(%options); $html_mail->lwp_ua($ua); #or set the options after creation $html_mail->lwp_ua->timeout(10);
This is very useful for specifying proxies, cookie parameters, etc. See LWP::UserAgent's manpage for all the details.
HTML::Mail objects are designed so that implementing persistence is easy.
The method dump dumps the object as a string. You can store this string in whatever way you wish to and later restore the object with the restore method. There exist also methods dump_file and restore_file that serialise and restore the objects to and from text files.
dump
restore
dump_file
restore_file
### initialisation my $html_mail = HTML::Mail->new( HTML => 'http://www.cpan.org', Text => 'This is the text representation of the webpage http://www.cpan.org', From => 'me@myhost.org', To => 'you@yourhost.org', Subject => 'CPAN webpage'); ### Serialise to string my $serialised = $html_mail->dump; ### Restore my $hmtl_mail_restored = HTML::Mail->restore($serialised); ### Serialise to disk ### If file exists, it's content will be erased my $file = '/tmp/stored_html_mail.data'; $html_mail->dump_file($file); ### Restore from file my $hmtl_mail_restored = HTML::Mail->restore_file($file);
None of these methods are meant for speed. Be also careful when restoring data that you don't trust since these methods basically use eval to restore the objects.
eval
All relevant data is stored, so you can send a restored email without fetching content again, or doing any HTML parsing if it was done before storing it.
As of version 0.02_00 the job of reusing an object to send several emails is optimised. This is mainly due to the fact that if the HTML content is changed, media that was included on the previous build will no longer be fetched and processed. However if there is new media referred to by the new HTML content, it will be fetched and made available for next builds.
This is particular useful for building customisable email campaigns, say putting the customer's name in the content.
The parsing of the HTML content is always done.
$html_mail->build(attribute => value)
regenerates the email. The attributes and values are the same as the ones in the new method.
The default values are merged in each build meanings that new attributes are sticky. The default value of an attribute is the most recent one specified or the classes default
attach_links is a subroutine that determines which links will be included in the email. Gets as the argument the href attribute of the tag and is expected to return a boolean, a true return value includes the link a false value doesn't.
href
boolean
#$html_mail is supposed to have been constructed for the sake of simplicity $html_mail->build(attach_links => sub{ my $link = shift; return $link =~ /\.pdf$/ } ) #This would include all links to pdf documents in the html
By default no links are included.
Be aware that a lot of email clients don't cope well with internally linked media This interface is considered experimental and subject to change, use at your own risk
This module uses MIME::Lite to send the emails. The default behaviour of the send method is to use sendmail, if this is not possible try sending the mail using smtp. <$html_mail-send('smtp','smtp_server.org')>>. Please consult the documentation for further details.
send
<$html_mail-
Try to use only correct HTML, at least it should be well formed.
In-line CSS in HTML documents gives better results with a wider range of email clients.
Don't use Javascript, this module will not include external javascript.
this module doesn't support frames/iframes so don't use them for now.
Reports on how clients display emails generated using this module are very welcome. Successfull/unsuccessful stories also welcome.
See the author's email at the end.
Full compatibility except for some CSS problems.
HTML OK but usually displays both text and HTML parts with the images as attachments
HTML is shown, not text and all media is ok.
Unknown (reports welcome)
HTML is shown. When the user prefers text, text content is shown together with a text rendering of the HTML.
None.
MIME::Lite (this module "inherits" from it)
HTML::Parser (used in this module to parse HTML)
LWP::UserAgent (used to fetch content)
The eg directory for some examples on how to use the package
Now considered alpha.
better tests at install time
more robust, try using something like uuidgen
Cláudio Valente, <plank@cpan.org>
I would like to thank the help of:
for bug reporting and submitting a patch
for bug reporting related with email rebuilding
for reporting a bug with relative links and several limitations regarding frames and iframes
Copyright 2003 by Cláudio Valente
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'Cláudio'. Assuming CP1252
To install HTML::Mail, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::Mail
CPAN shell
perl -MCPAN -e shell install HTML::Mail
For more information on module installation, please visit the detailed CPAN module installation guide.