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.000007
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

PERL VERSION

83       This library should run on perls released even a long time ago.  It
84       should work on any version of perl released in the last five years.
85
86       Although it may work on older versions of perl, no guarantee is made
87       that the minimum required version will not be increased.  The version
88       may be increased for any reason, and there is no promise that patches
89       will be accepted to lower the minimum required perl.
90

ENCODING ISSUES

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

AUTHOR

126       This code was written in 2009 by Ricardo SIGNES.  It was based on a
127       previous implementation by Hans Dieter Pearcey written in 2006.
128
129       The development of this code was sponsored by Pobox.com.  Thanks,
130       Pobox!
131

AUTHOR

133       Ricardo Signes <rjbs@cpan.org>
134

CONTRIBUTORS

136       •   Charlie Garrison <garrison@zeta.org.au>
137
138       •   fREW Schmidt <frioux@gmail.com>
139
140       •   hdp <hdp@1bcdbe44-fcfd-0310-b51b-975661d93aa0>
141
142       •   Kaitlyn Parkhurst <symkat@symkat.com>
143
144       •   Ricardo Signes <cpan@semiotic.systems>
145
146       •   Ricardo Signes <rjbs@semiotic.systems>
147

149       This software is copyright (c) 2023 by Ricardo Signes.
150
151       This is free software; you can redistribute it and/or modify it under
152       the same terms as the Perl 5 programming language system itself.
153
154
155
156perl v5.36.0                      2023-01-20               Email::MIME::Kit(3)
Impressum