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 bare email, 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. An email without 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; [] gives undef (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:00 becomes Sat, 07 Nov 2026 10:00:00 +1100; Z becomes +0000.
asURLs: <url> separated by commas; [] gives undef.
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.