Encode:...:Header(3pm)

📦
version 5.42.3 · 17 versions
, in alpine 3.24

💖 NAME 💖

okay so welcome to the Encode:...:Header(3pm) page from the Perl Programmers Reference Guide — yes bestie, that title is giving colon chaos, but the module we're actually hyping is Encode::MIME::Header, and it does MIME encoding for an unstructured email header. periodt. ✨

✨ SYNOPSIS ✨

here's the whole vibe in code, no edits, no cap:

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

🦋 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 part is important — it cannot be used directly for the whole header with the field name, or for structured header fields like From, To, Cc, Message-Id, etc... 🫶

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

🌸 DESCRIPTION 🌸

The decode method takes an unstructured field body of the email header (or an RFC 822 (https://tools.ietf.org/html/rfc822) 'text' token) as its input, and it 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 each sequence of bytes gets decoded with the corresponding MIME charset using the Encode module, and finally one output string is returned. 💅

Text parts of the input string which do not contain MIME encoded-word stay unmodified in the output string. 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, and MIME-Header can decode both of them. 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. 😭

The encode method takes a scalar string as its input and uses the strict UTF-8 encoder to encode it to UTF-8 bytes. Then that sequence of UTF-8 bytes is encoded into MIME encoded-words (MIME-Header and MIME-B use a Base64 variant, while MIME-Q uses a Quoted-Printable variant), where each MIME encoded-word is limited to 75 characters. MIME encoded-words are separated by "CRLF SPACE" and joined into one output string. That output string is suitable for an unstructured field body of the email header. 🔥

Both encode and decode methods propagate CHECK flags when encoding and decoding the MIME charset. 🎀

💀 BUGS 💀

okay bestie, this is the part where we scream. 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! 🚨

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 used a not-strict utf8 decoder too, and additionally called the decode method with an 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 the strict UTF-8 encoder and decoder, and CHECK flags are correctly propagated. 💖

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). Due to the aforementioned bugs in previous versions of the MIME encoder, there's a less strict compatible mode for the MIME decoder, and that mode is used by default. It should be able to decode MIME encoded-words encoded by pre 2.22 versions of this module. However, note that this is not correct according to RFC 2047 (https://tools.ietf.org/html/rfc2047). 🫠

In default not strict mode, the MIME decoder attempts to decode every substring which looks like a MIME encoded-word. Therefore, the MIME encoded-words don't need to be separated by white space. To enforce a correct strict mode, set the variable $Encode::MIME::Header::STRICT_DECODE to 1, e.g. by localizing it like this:

use Encode::MIME::Header;
local $Encode::MIME::Header::STRICT_DECODE = 1;

and that's the strict-mode slay. 💅

👑 AUTHORS 👑

Pali <pali@cpan.org> — that's the author, bestie. 👑

🌈 SEE ALSO 🌈

and that's the whole page, bestie! 🎀 this gem is from perl v5.42.3, dated 2026-11-03, and the manual page is still Encode:...:Header(3pm). mwah 💋

📦 where this page comes from