Email::MIME::Kit(3pm)

💌 Email::MIME::Kit(3pm) — build messages from templates

okay so you found the Email::MIME::Kit(3pm) page, part of the User Contributed Perl Documentation, and bestie, this one is iconic. it's a whole templating system for entire email messages, not just little text chunks. no cap. let's get into it 💅

---

✨ NAME ✨

Email::MIME::Kit — build messages from templates 🎀

---

🌸 VERSION 🌸

version 3.000008 — yes she's got a version, and yes it's long, we love that for her 🦋

---

🧚 SYNOPSIS 🧚

here's the vibe, in code, verbatim, do not touch:

  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, { ... });

look at that. you make a kit, you assemble it with your template vars, you send the thing. main character energy fr fr 🌈

---

💖 DESCRIPTION 💖

so Email::MIME::Kit is a templating system for email messages. but here's the thing — instead of being yet another templating system for chunks of text, it makes it easy to build complete email messages. periodt.

it handles all of this for you, no stress:

• the construction of multipart messages
• text and HTML alternatives
• attachments
• interpart linking
• string encoding
• parameter validation

and the way that nearly every part of Email::MIME::Kit is a replaceable component?? lowkey obsessed. but also — the stock configuration is probably enough for most use, so don't overthink it bestie 🫶

a message kit gets stored as a directory, and it 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 it 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 — like, for example, to include that logo.jpg from above:

  <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. that's a real note from the real docs, not me being dramatic (for once).

so the manifest above would build a multipart alternative message. here's what everybody sees:

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

and then the message would be assembled and returned as an Email::MIME object — just as easily as suggested in the "SYNOPSIS" above. slay 💅

---

🐪 PERL VERSION 🐪

this library should run on perls released even a long time ago. it should work on any version of perl released in the last five years.

although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. the version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. that's just how it is, bestie 😭

---

🔤 ENCODING ISSUES 🔤

in general, "it should all just work" ... starting in version v3. iconic behaviour honestly.

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. and this, further, means that strings passed to the assemble method for use in rendering should also be text strings. keep that in mind 🧠

now, 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. and 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. like, none. 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. which means: some review of kits is in order when upgrading from earlier versions of Email::MIME::Kit. consider this your gentle reminder, bestie. go check your kits 🫶

---

👑 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 (yes, again, and that's on purpose) 👑

Ricardo Signes <cpan@semiotic.systems> 💌

---

🦋 CONTRIBUTORS 🦋

these legends helped out, show them love:

• Charlie Garrison <garrison@zeta.org.au>
• fREW Schmidt <frioux@gmail.com>
• hdp <hdp@1bcdbe44-fcfd-0310-b51b-975661d93aa0>
• Kaitlyn Parkhurst <symkat@symkat.com>
• Ricardo Signes <rjbs@semiotic.systems>

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2023 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. iykyk 🎀

---

and that's the whole page bestie, you ate it. this doc came to you from perl v5.36.0, dated 2023-09-20, and it's the Email::MIME::Kit(3pm) page — now go build some gorgeous multipart emails, you absolute icon 🌈💖✨