.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Email::MIME::Kit 3pm" .TH Email::MIME::Kit 3pm "2021-01-08" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Email::MIME::Kit \- build messages from templates .SH "VERSION" .IX Header "VERSION" version 3.000006 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Email::MIME::Kit; \& \& my $kit = Email::MIME::Kit\->new({ source => \*(Aqmkits/sample.mkit\*(Aq }); \& \& my $email = $kit\->assemble({ \& account => $new_signup, \& verification_code => $token, \& ... and any other template vars ... \& }); \& \& $transport\->send($email, { ... }); .Ve .SH "DESCRIPTION" .IX Header "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. .PP It handles the construction of multipart messages, text and \s-1HTML\s0 alternatives, attachments, interpart linking, string encoding, and parameter validation. .PP 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: .PP .Vb 5 \& sample.mkit/ \& manifest.json \& body.txt \& body.html \& logo.jpg .Ve .PP The manifest file tells Email::MIME::Kit how to put it all together, and might look something like this: .PP .Vb 10 \& { \& "renderer": "TT", \& "header": [ \& { "From": "WY Corp " }, \& { "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" } ] \& } \& ] \& } .Ve .PP \&\fBInline images\fR may be accessed with the function \f(CW\*(C`cid_for\*(C'\fR, for example to include the above logo.jpg: .PP .Vb 1 \& .Ve .PP \&\fBPlease note:\fR the assembly of \s-1HTML\s0 documents as multipart/related bodies may be simplified with an alternate assembler in the future. .PP The above manifest would build a multipart alternative message. \s-1GUI\s0 mail clients would see a rendered \s-1HTML\s0 document with the logo graphic visible from the attachment. Text mail clients would see the plaintext. .PP Both the \s-1HTML\s0 and text parts would be rendered using the named renderer, which here is Template-Toolkit. .PP The message would be assembled and returned as an Email::MIME object, just as easily as suggested in the \*(L"\s-1SYNOPSIS\*(R"\s0 above. .SH "ENCODING ISSUES" .IX Header "ENCODING ISSUES" In general, \*(L"it should all just work\*(R" ... starting in version v3. .PP Email::MIME::Kit assumes that any file read for the purpose of becoming a \&\f(CW\*(C`text/*\*(C'\fR\-type part is encoded in \s-1UTF\-8.\s0 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 \f(CW\*(C`assemble\*(C'\fR method for use in rendering should also be text strings. .PP 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 \&\fImanifest.json\fR file might contain: .PP .Vb 4 \& "header": [ \& { "Subject": "Message for [% customer_name %]" }, \& ... \& ] .Ve .PP \&...while a template on disk might contain: .PP .Vb 2 \& Dear [% customer_name %], \& ... .Ve .PP If the customer's name isn't \s-1ASCII,\s0 there was no right way to pass it in. The template on disk would expect \s-1UTF\-8,\s0 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. .SH "AUTHOR" .IX Header "AUTHOR" This code was written in 2009 by Ricardo \s-1SIGNES.\s0 It was based on a previous implementation by Hans Dieter Pearcey written in 2006. .PP The development of this code was sponsored by Pobox.com. Thanks, Pobox! .SH "AUTHOR" .IX Header "AUTHOR" Ricardo Signes .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Charlie Garrison .IP "\(bu" 4 fREW Schmidt .IP "\(bu" 4 hdp .IP "\(bu" 4 Kaitlyn Parkhurst .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2018 by Ricardo Signes. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.