1Email::MIME::Kit(3)   User Contributed Perl Documentation  Email::MIME::Kit(3)
2
3
4

NAME

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

VERSION

9       version 3.000006
10

SYNOPSIS

12         use Email::MIME::Kit;
13
14         my $kit = Email::MIME::Kit->new({ source => 'mkits/sample.mkit' });
15
16         my $email = $kit->assemble({
17           account           => $new_signup,
18           verification_code => $token,
19           ... and any other template vars ...
20         });
21
22         $transport->send($email, { ... });
23

DESCRIPTION

25       Email::MIME::Kit is a templating system for email messages.  Instead of
26       trying to be yet another templating system for chunks of text, it makes
27       it easy to build complete email messages.
28
29       It handles the construction of multipart messages, text and HTML
30       alternatives, attachments, interpart linking, string encoding, and
31       parameter validation.
32
33       Although nearly every part of Email::MIME::Kit is a replaceable
34       component, the stock configuration is probably enough for most use.  A
35       message kit will be stored as a directory that might look like this:
36
37         sample.mkit/
38           manifest.json
39           body.txt
40           body.html
41           logo.jpg
42
43       The manifest file tells Email::MIME::Kit how to put it all together,
44       and might look something like this:
45
46         {
47           "renderer": "TT",
48           "header": [
49             { "From": "WY Corp <noreplies@wy.example.com>" },
50             { "Subject": "Welcome aboard, [% recruit.name %]!" }
51           ],
52           "alternatives": [
53             { "type": "text/plain", "path": "body.txt" },
54             {
55               "type": "text/html",
56               "path": "body.html",
57               "container_type": "multipart/related",
58               "attachments": [ { "type": "image/jpeg", "path": "logo.jpg" } ]
59             }
60           ]
61         }
62
63       Inline images may be accessed with the function "cid_for", for example
64       to include the above logo.jpg:
65
66           <img style="margin: 0 auto" src="cid:[% cid_for("logo.jpg") %]">
67
68       Please note: the assembly of HTML documents as multipart/related bodies
69       may be simplified with an alternate assembler in the future.
70
71       The above manifest would build a multipart alternative message.  GUI
72       mail clients would see a rendered HTML document with the logo graphic
73       visible from the attachment.  Text mail clients would see the
74       plaintext.
75
76       Both the HTML and text parts would be rendered using the named
77       renderer, which here is Template-Toolkit.
78
79       The message would be assembled and returned as an Email::MIME object,
80       just as easily as suggested in the "SYNOPSIS" above.
81

ENCODING ISSUES

83       In general, "it should all just work" ... starting in version v3.
84
85       Email::MIME::Kit assumes that any file read for the purpose of becoming
86       a "text/*"-type part is encoded in UTF-8.  It will decode them and work
87       with their contents as text strings.  Renderers will be passed text
88       strings to render, and so on.  This, further, means that strings passed
89       to the "assemble" method for use in rendering should also be text
90       strings.
91
92       In older versions of Email::MIME::Kit, files read from disk were read
93       in raw mode and then handled as octet strings.  Meanwhile, the
94       manifest's contents (and, thus, any templates stored as strings in the
95       manifest) were decoded into text strings.  This could lead to serious
96       problems.  For example: the manifest.json file might contain:
97
98         "header": [
99           { "Subject": "Message for [% customer_name %]" },
100           ...
101         ]
102
103       ...while a template on disk might contain:
104
105         Dear [% customer_name %],
106         ...
107
108       If the customer's name isn't ASCII, there was no right way to pass it
109       in.  The template on disk would expect UTF-8, but the template in the
110       manifest would expect Unicode text.  Users prior to v3 may have taken
111       strange steps to get around this problem, understanding that some
112       templates were treated differently than others.  This means that some
113       review of kits is in order when upgrading from earlier versions of
114       Email::MIME::Kit.
115

AUTHOR

117       This code was written in 2009 by Ricardo SIGNES.  It was based on a
118       previous implementation by Hans Dieter Pearcey written in 2006.
119
120       The development of this code was sponsored by Pobox.com.  Thanks,
121       Pobox!
122

AUTHOR

124       Ricardo Signes <rjbs@cpan.org>
125

CONTRIBUTORS

127       •   Charlie Garrison <garrison@zeta.org.au>
128
129       •   fREW Schmidt <frioux@gmail.com>
130
131       •   hdp <hdp@1bcdbe44-fcfd-0310-b51b-975661d93aa0>
132
133       •   Kaitlyn Parkhurst <symkat@symkat.com>
134

136       This software is copyright (c) 2018 by Ricardo Signes.
137
138       This is free software; you can redistribute it and/or modify it under
139       the same terms as the Perl 5 programming language system itself.
140
141
142
143perl v5.36.0                      2022-07-22               Email::MIME::Kit(3)
Impressum