NAME
Data::JSEmail - Convert between Email::MIME and the JSON format from RFC 8621 (JMAP Mail)
HEADER FORMS
One codec for the parsed header forms of RFC 8621 S4.1.2, used in both directions: parse and make use it for every header field they read or write, the convenience properties (from, subject, sentAt, ...) included. A form is named as in a property: asText, asAddresses, asGroupedAddresses, asMessageIds, asDate, asURLs, and asRaw for Raw (undef, '' and 'Raw' mean asRaw too).
header_value($form, $raw_values, all => 0|1)
The value of a header:Name:$form[:all] property, from the Raw value of each instance of the field in message order (an arrayref; a single string is taken as a one-item list; undef items are skipped). Without all, the parsed value of the last instance, or undef if there is none; with all => 1, an arrayref of the parsed value of each instance ([] if none). Dies ("Unknown header form '...'\n") for a form it does not know.
header_property($headers, $property)
header_value over an EmailHeader list ([{name, value}, ...], the headers property parse returns) for a whole property name such as header:Resent-To:asAddresses:all; names match case-insensitively. Dies ("Invalid header property '...'\n") when parse_header_property rejects the name.
parse_header_property($property)
($name, $form, $all) for a valid header:{name}[:as{form}][:all] property ($form is asRaw when none is given, $all is 0 or 1), or the empty list if the name is not a header property, the field name is not printable ASCII without a colon (S4.1.3), or the form is unknown. It does not consult header_form_allowed.
format_header($form, $value)
The create side, the inverse of header_value for one instance: the Raw value (with the usual leading space) to write for $value in $form, such that header_value($form, [$raw]) gives $value back. The result is a character string; make writes it as UTF-8.
- asText: RFC 2047 encoded-words (UTF-8, Q) when the text is not printable ASCII or holds something that looks like an encoded-word (
=?); line breaks become spaces. - asAddresses:
name <email>or a bareemail, comma separated. A name is written as atoms, as a quoted-string ("and\escaped), or as encoded-words if it is not ASCII or contains=?. A local part that is not a dot-atom is quoted. Anemailwithout an@is written as given (S4.1.2.3 allows it, and S4.6 lets a draft be invalid); RFC 6532 UTF-8 addresses are kept.[]gives an empty value. - asGroupedAddresses: as asAddresses, with each group that has a name written as
Name: mailbox, ...;(Name:;when empty) and the mailboxes of a group with a null name written ungrouped. - asMessageIds:
<id>separated by spaces;[]givesundef(no field: an empty one would read back as null, not []). - asDate: an RFC 3339 date-time (a JMAP Date) written as an RFC 5322 date-time, keeping the offset:
2026-11-07T10:00:00+11:00becomesSat, 07 Nov 2026 10:00:00 +1100;Zbecomes+0000. - asURLs:
<url>separated by commas;[]givesundef. - asRaw: the value as given.
A $value of undef gives undef (no header field). A value of the wrong type or shape dies with "Invalid $form header value: ...\n": for example a Date that is not RFC 3339 or not a real date, a message id or URL that is empty or holds whitespace or angle brackets, an EmailAddress without a string email, a domain with spaces or specials, a Raw value with NUL or with a line break that is not a fold (CRLF then whitespace). An unknown form dies like header_value.
header_form_allowed($field, $form)
1 if the parsed form may be used with that header field (the table in RFC 8621 S4.1.2: Raw is allowed for every field; a field defined in RFC 5322 or RFC 2369 only with the forms listed for it; any other field with every form), else 0. An unknown form is 0.
Header properties in make
make takes header:{name}[:as{form}][:all] properties on the Email and on any EmailBodyPart directly: each is checked with parse_header_property and header_form_allowed and written with format_header; :all takes a list and writes one field per item, and a Raw value given as a list does the same. A Raw value is written as given, less one leading space (the writer puts one after the colon). make dies on an invalid property name, a form not allowed for the field, a value format_header refuses, or an :all value that is not a list. A header:* property wins over the convenience property for the same field.
AUTHOR
Bron Gondwana, <brong at cpan.org>
LICENSE AND COPYRIGHT
Copyright 2026 Fastmail Pty Ltd.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself; that is, either the GNU General Public License as published by the Free Software Foundation (version 1, or at your option any later version), or the Artistic License.
See http://dev.perl.org/licenses/ and the LICENSE file included with this distribution for more information.