/ 
Email-Template-0.02
River stage zero No dependents
/ Email::Template

NAME

Email::Template - Send "multipart/alternative" (text & html) email from a Template

VERSION

Version 0.02

SYNOPSIS

use Email::Template;
Email::Template->send( '/path/to/email/template.tt2',
    {
        From    => 'sender@domain.tld',
        To      => 'recipient@domain.tld',
        Subject => 'Email::Template is easy to use',

        tt_vars => { key => $value, ... },
        convert => { rightmargin => 80, no_rowspacing => 1, ... }
    }
) or warn "could not send the email";

DESCRIPTION

This is a fairly simple interface to generate "multipart/alternative" emails with both "text/html" and "text/plain" components using a single HTML based Template Toolkit template.

The HTML, once processed by Template Toolkit, is converted to text using HTML::FormatText::WithLinks::AndTables. Both HTML and text versions are then attached and sent via MIME::Lite.

Be sure to validate your sender and recipient addresses first (ie. Email::Valid->rfc822 ).

A NOTE ABOUT CHARACTER SETS

If your template files are non-ASCII, be sure to pass { ENCODING => 'utf-8' } (or whatever) in the tt_new argument; otherwise, you will get gibberish in the emails.

The text/html and text/plain parts are encoded using utf-8 by default, or pass in 'charset' to choose a different one (e.g. iso-8859-1).

EXPORTS

None by default.

METHODS

send

The first argument to send() is the path to the Template file. Absolute paths are allowed. If the path is relative, it works the same as when using Template Toolkit.

The second argument to send() is a hash reference containing the following possible options.

MIME::Lite

# REQUIRED

    From    => 'sender@domain.tld',
    To      => 'recipient@domain.tld',
    Subject => 'a subject for your email',

# OPTIONAL

    # charset to use for the text and html MIME parts (default utf-8)
    charset => 'utf-8',

    # arguments to be passed to MIME::Lite send()
    mime_lite_send => ['smtp', 'some.host', Debug=>1 ],

    # additional attachments to add via MIME::Lite attach()
    mime_lite_attach => [ {Type=>...,Data=>...}, ... ],

    # do not send(), just return the prepared MIME::Lite object
    return_mime_lite => 1,

Template Toolkit

# OPTIONAL

    # configuration options passed into Template->new()
    tt_new  => { INCLUDE_PATH => '/path/to/templates', ... },

    # variables to interpolate via Template->process()
    tt_vars => { key => $value, ... },

HTML::FormatText::WithLinks::AndTables

# OPTIONAL

    # configuration options passed into convert()
    convert => { rm => 80, no_rowspacing => 1, ... }

NOTE: all additional arguments not explicitely mentioned above will be passed into MIME::Lite->new()

Assuming "return_mime_lite => 1" was not passed in the arguments list, on success send() returns the value of MIME::Lite->as_string(), or on failure returns nothing.

SEE ALSO

Template
MIME::Lite
HTML::FormatText::WithLinks::AndTables

AUTHOR

Shaun Fryer, <pause.cpan.org at sourcery.ca>

CONTRIBUTORS

Ryan D Johnson, <ryan@innerfence.com>, charset support

BUGS

Please report any bugs or feature requests to bug-email-template at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Email-Template. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Email::Template

You can also look for information at:

ACKNOWLEDGEMENTS

Everybody. :) http://en.wikipedia.org/wiki/Standing_on_the_shoulders_of_giants

COPYRIGHT & LICENSE

Copyright 2008 Shaun Fryer, all rights reserved.

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