HTML::Mail - Perl extension for sending emails with embedded HTML and media

HTML-Mail documentation  | view source Contained in the HTML-Mail distribution.

Index

NAME

Top

HTML::Mail - Perl extension for sending emails with embedded HTML and media

SYNOPSIS

Top

	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');

DESCRIPTION

Top

HTML::Mail is supposed to help with the task of sending emails with HTML and images (or other media) embedded or externally linked. 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 all you want is to send text-only email, you probably won't find this module useful at all, or at best a huge overkill.

Method Summary

new

Constructor. Initialises the object. See the attributes section

build

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.

lwp_ua

Returns the LWP::UserAgent object used internally so that it can the customized

dump

Serializes the object to a string

dump_file

Serializes the object to a file

restore

Restores previously serialized object from a string

restore_file

Restores previously serialized object from a file

gen_cid

Method to generate cids. Receives $self and the uri to associate the cid to. If you need to generate your own cids (say, add www.host.com) you should subclass this method.

Attributes

All attributes are case sensitive.

	my $html_mail = HTML::Mail->new(attribute => value);

	$html_mail->build(attribute => value);

Constructor supports these attributes:

HTML [URI or STRING]

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>';
Text [URI or STRING]

The URL of Text data to send in email. Similar to the HTML attribute. You can also specify the actual text data as a string.

From, To, Subject

Inherited from MIME::Lite. Sender, Recipient and Subject of the message.

html_charset

Charset of the HTML part of the email. Defaults to iso-8859-15.

text_charset

Charset of the text part of the email. Defaults to iso-8859-15.

lwp_ua

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.

inline_css

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.

attach_uri

Controls which media is attached in the email or referenced to an external source. See Conditional attachment of media

Controls which links are also included in the email. See Linked Media.

strict_download

Boolean controling whether to die when downloading of media fails. Default True so failing to download media results in a fatal error.

If you are sending email from content with broken images it might be a good idea to turn this off since otherwise the email building procedure will fail.

Use at your own risk.

ADVANCED USAGE

Top

LWP::UserAgent options

The lwp_ua method returns the instance of LWP::UserAgent used to make the request. Using this method you can change its options to your needs.

	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.

Persistence

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 serialize and restore the objects to and from text files.

	### 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 $serial = $html_mail->dump;

	### Restore
	my $hmtl_mail_restored = HTML::Mail->restore($serial);

	### Serialise to disk
	### If file exists, its 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.

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.

Rebuilding emails

As of version 0.02_00 the job of reusing an object to send several emails is optimized. 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 customizable 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 meaning that new attributes are sticky. The default value of an attribute is the most recent one specified or the classes default

Conditional attachment of media

For some reason, there might be some media which should not be attached to the email, but fetched at view time. The attach_uri method controls this behaviour. By default all media is attached. This behaviour can be changed either by inheriting from HTML::Mail and redefining the attach_uri method or by specifying the attach_uri field at construction.

The method's signature is:

  package MyMail;
  use base ('HTML::Mail');

  sub attach_uri{
	my ($self, $uri) = @_;

	return 1; #to attach, 0 to not attach
  }

Where $uri is an URI object. (by overloading it can be treated just like a string in most circumstances)

Or if you prefer

  my $mail = HTML::Mail->new(
    #some parameters
    'attach_uri' => sub {my $uri = shift; return $uri->scheme !~ /^(ftp|file)/i}
  );

will not attach any media fetched via ftp or from the local file system.

Linked Media

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.

	#$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

COMPATIBILITY

Top

Sending email

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').

The author has received a report that at least on a Windows 2000 Server system using

  $html_mail->send('smtp','mailhost');

was successful in sending the email. So far this behaviour has not been reproduced on any other system so use this tip at your own risk. If you have any information regarding this issue, please contact the author.

Please consult the MIME::Lite documentation for further details.

Suggestions

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, and most clients won't interpret/run the code at all.

This module doesn't support frames/iframes so don't use them for now. Client support for frames is unknown to the author.

Email Clients

Reports on how clients display emails generated using this module are very welcome. Successful/unsuccessful stories also welcome.

See the author's email at the end.

Evolution 1.08

Full compatibility except for some CSS problems.

Kmail 1.4.3

HTML OK but usually displays both text and HTML parts with the images as attachments

Yahoo webmail (http://mail.yahoo.com)

HTML is shown, not text and all media is OK.

Hotmail (http://www.hotmail.com)

Unknown (reports welcome)

Outlook Express 6

HTML is shown. When the user prefers text, text content is shown together with a text rendering of the HTML.

Eudora

Unknown (reports welcome)

EXPORT

Top

None.

SEE ALSO

Top

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

DEVELOPMENT STATUS

Top

Considered beta.

TODO LIST

Top

Tests

better tests at install time

AUTHOR

Top

Cláudio Valente, <plank@cpan.org>

Bug Reporters

Top

I would like to thank the help of:

Matthew Albright

for bug reporting and submitting a patch

Daniel Wijnands

for bug reporting related with email rebuilding

Calvin Huang

for reporting a bug with relative links and several limitations regarding frames and iframes

Eduardo Correia

for reporting a bug regarding documents with no base URI specified

Marc Logghe

for making suggestions regarding handling of broken links (this suggestion eventually led to the strict_download flag)

COPYRIGHT AND LICENSE

Top

Copyright 2007 by Cláudio Valente

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

HTML-Mail documentation  | view source Contained in the HTML-Mail distribution.