NAME

       Email::MIME::Kit - build messages from templates

VERSION

       version 3.000006

SYNOPSIS

         use Email::MIME::Kit;

         my $kit = Email::MIME::Kit->new({ source => 'mkits/sample.mkit' });

         my $email = $kit->assemble({
           account           => $new_signup,
           verification_code => $token,
           ... and any other template vars ...
         });

         $transport->send($email, { ... });

DESCRIPTION

       Email::MIME::Kit is a templating system for email messages.  Instead of trying to be yet
       another templating system for chunks of text, it makes it easy to build complete email
       messages.

       It handles the construction of multipart messages, text and HTML alternatives,
       attachments, interpart linking, string encoding, and parameter validation.

       Although nearly every part of Email::MIME::Kit is a replaceable component, the stock
       configuration is probably enough for most use.  A message kit will be stored as a
       directory that might look like this:

         sample.mkit/
           manifest.json
           body.txt
           body.html
           logo.jpg

       The manifest file tells Email::MIME::Kit how to put it all together, and might look
       something like this:

         {
           "renderer": "TT",
           "header": [
             { "From": "WY Corp <noreplies@wy.example.com>" },
             { "Subject": "Welcome aboard, [% recruit.name %]!" }
           ],
           "alternatives": [
             { "type": "text/plain", "path": "body.txt" },
             {
               "type": "text/html",
               "path": "body.html",
               "container_type": "multipart/related",
               "attachments": [ { "type": "image/jpeg", "path": "logo.jpg" } ]
             }
           ]
         }

       Inline images may be accessed with the function "cid_for", for example to include the
       above logo.jpg:

           <img style="margin: 0 auto" src="cid:[% cid_for("logo.jpg") %]">

       Please note: the assembly of HTML documents as multipart/related bodies may be simplified
       with an alternate assembler in the future.

       The above manifest would build a multipart alternative message.  GUI mail clients would
       see a rendered HTML document with the logo graphic visible from the attachment.  Text mail
       clients would see the plaintext.

       Both the HTML and text parts would be rendered using the named renderer, which here is
       Template-Toolkit.

       The message would be assembled and returned as an Email::MIME object, just as easily as
       suggested in the "SYNOPSIS" above.

ENCODING ISSUES

       In general, "it should all just work" ... starting in version v3.

       Email::MIME::Kit assumes that any file read for the purpose of becoming a "text/*"-type
       part is encoded in UTF-8.  It will decode them and work with their contents as text
       strings.  Renderers will be passed text strings to render, and so on.  This, further,
       means that strings passed to the "assemble" method for use in rendering should also be
       text strings.

       In older versions of Email::MIME::Kit, files read from disk were read in raw mode and then
       handled as octet strings.  Meanwhile, the manifest's contents (and, thus, any templates
       stored as strings in the manifest) were decoded into text strings.  This could lead to
       serious problems.  For example: the manifest.json file might contain:

         "header": [
           { "Subject": "Message for [% customer_name %]" },
           ...
         ]

       ...while a template on disk might contain:

         Dear [% customer_name %],
         ...

       If the customer's name isn't ASCII, there was no right way to pass it in.  The template on
       disk would expect UTF-8, but the template in the manifest would expect Unicode text.
       Users prior to v3 may have taken strange steps to get around this problem, understanding
       that some templates were treated differently than others.  This means that some review of
       kits is in order when upgrading from earlier versions of Email::MIME::Kit.

AUTHOR

       This code was written in 2009 by Ricardo SIGNES.  It was based on a previous
       implementation by Hans Dieter Pearcey written in 2006.

       The development of this code was sponsored by Pobox.com.  Thanks, Pobox!

AUTHOR

       Ricardo Signes <rjbs@cpan.org>

CONTRIBUTORS

       •   Charlie Garrison <garrison@zeta.org.au>

       •   fREW Schmidt <frioux@gmail.com>

       •   hdp <hdp@1bcdbe44-fcfd-0310-b51b-975661d93aa0>

       •   Kaitlyn Parkhurst <symkat@symkat.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2018 by Ricardo Signes.

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