Encode...Header(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

✨ Encode::MIME::Header — the MIME glow-up for your email headers ✨

okay so bestie, this is a Perl manual page — Encode::MIME::Header from the Perl Programmers Reference Guide — and it's literally the module that makes your unstructured email headers speak MIME. iykyk 💅

🎀 NAME 🎀

Encode::MIME::Header — MIME encoding for an unstructured email header 🦋

🌸 SYNOPSIS 🌸

use Encode qw(encode decode);

my $mime_str = encode("MIME-Header", "Sample:Text \N{U+263A}");
# $mime_str is "=?UTF-8?B?U2FtcGxlOlRleHQg4pi6?="

my $mime_q_str = encode("MIME-Q", "Sample:Text \N{U+263A}");
# $mime_q_str is "=?UTF-8?Q?Sample=3AText_=E2=98=BA?="

my $str = decode("MIME-Header",
    "=?ISO-8859-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=\r\n " .
    "=?ISO-8859-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?="
);
# $str is "If you can read this you understand the example."

use Encode qw(decode :fallbacks);
use Encode::MIME::Header;
local $Encode::MIME::Header::STRICT_DECODE = 1;
my $strict_string = decode("MIME-Header", $mime_string, FB_CROAK);
# use strict decoding and croak on errors

so yeah, that last bit is the strict girlie mode: decode hard, croak on errors, no vibes spared 😭✨

🧚 ABSTRACT 🧚

This module implements RFC 2047 (https://tools.ietf.org/html/rfc2047) MIME encoding for an unstructured field body of the email header. It can also be used for the RFC 822 (https://tools.ietf.org/html/rfc822) 'text' token. 🌈

however — and this is the important part — it literally cannot be used directly for the whole header with the field name, or for structured header fields like From, To, Cc, Message-Id, etc... so don't even try it bestie 💀

There are 3 encoding names supported by this module: "MIME-Header", "MIME-B" and "MIME-Q". periodt 💅

👑 DESCRIPTION 👑

🦋 the Decode method

Decode method takes an unstructured field body of the email header (or RFC 822 (https://tools.ietf.org/html/rfc822) 'text' token) as its input and decodes each MIME encoded-word from the input string to a sequence of bytes according to RFC 2047 (https://tools.ietf.org/html/rfc2047) and RFC 2231 (https://tools.ietf.org/html/rfc2231). ✨

Then — and this is the main character energy part — each sequence of bytes with the corresponding MIME charset gets decoded with the Encode module, and finally one output string is returned. 🎀

  • Text parts of the input string which do not contain a MIME encoded-word stay unmodified in the output string. no touchy.
  • Folded newlines between two consecutive MIME encoded-words are discarded; others are preserved in the output string.
  • "MIME-B" can decode the Base64 variant.
  • "MIME-Q" can decode the Quoted-Printable variant.
  • "MIME-Header" can decode both of them. versatile queen 👑

If the Encode module does not support a particular MIME charset or the chosen variant, then an action based on CHECK flags is performed (by default, the MIME encoded-word is not decoded). fr fr 🫶

💖 the Encode method

Encode method takes a scalar string as its input and uses a strict UTF-8 encoder for encoding it to UTF-8 bytes. Then a sequence of UTF-8 bytes is encoded into MIME encoded-words — where "MIME-Header" and "MIME-B" use a Base64 variant while "MIME-Q" uses a Quoted-Printable variant — and each MIME encoded-word is limited to 75 characters. 🌸

MIME encoded-words are separated by "CRLF SPACE" and joined to one output string. The output string is suitable for an unstructured field body of the email header. slay ✨

🫶 the flags bit

Both encode and decode methods propagate CHECK flags when encoding and decoding the MIME charset. literally both of them. 💜

💀 BUGS 💀

okay so this is the part where we hold hands and read the warnings together, because the old versions were messing up and we do not stan 🚫
  • Versions prior to 2.22 (part of Encode 2.83) have a malfunctioning decoder and encoder. The MIME encoder infamously inserted additional spaces or discarded white spaces between consecutive MIME encoded-words, which led to invalid MIME headers produced by this module. The MIME decoder had a tendency to discard white spaces, incorrectly interpret data, or attempt to decode Base64 MIME encoded-words as Quoted-Printable. 😭 These problems were fixed in version 2.22. It is highly recommended not to use any version prior 2.22! fr fr, don't.
  • Versions prior to 2.24 (part of Encode 2.87) ignored CHECK flags. The MIME encoder used a not strict utf8 encoder for input Unicode strings, which could lead to invalid UTF-8 sequences. The MIME decoder also used a not strict utf8 decoder and additionally called the decode method with a "Encode::FB_PERLQQ" flag (so user-specified CHECK flags were ignored 🙈). Moreover, it automatically croaked when a MIME encoded-word contained an unknown encoding. Since version 2.24, this module uses a strict UTF-8 encoder and decoder. And CHECK flags are correctly propagated. periodt 💅
  • Since version 2.22 (part of Encode 2.83), the MIME encoder should be fully compliant to RFC 2047 (https://tools.ietf.org/html/rfc2047) and RFC 2231 (https://tools.ietf.org/html/rfc2231). Because of the aforementioned bugs in previous versions of the MIME encoder, there's a less strict compatible mode for the MIME decoder, and it's the one used by default. It should be able to decode MIME encoded-words encoded by pre-2.22 versions of this module. However — heads up bestie — note that this is not correct according to RFC 2047 (https://tools.ietf.org/html/rfc2047). 💀
  • In the default, not-strict mode, the MIME decoder attempts to decode every substring which looks like a MIME encoded-word. Therefore, the MIME encoded-words do not need to be separated by white space. To enforce the correct strict mode, set the variable $Encode::MIME::Header::STRICT_DECODE to 1 — e.g. by localizing it:
use Encode::MIME::Header;
local $Encode::MIME::Header::STRICT_DECODE = 1;

glow-up unlocked ✨

💅 AUTHORS 💅

Pali <pali@cpan.org> — iconic, we love them for this 🫶

🌈 SEE ALSO 🌈

and that's the whole page bestie, literally no cap 💖 this was the Encode::MIME::Header(3perl) manual page from perl v5.44.0, dated 2026-10-17 — go forth and encode your headers correctly, and remember: never use anything older than 2.22 🎀🦋🌸💜✨

📦 where this page comes from