Mail::M...ddresses(3)

📦
version 4.04 · 11 versions
, in fedora 44

✨ NAME ✨

okay so bestie, meet Mail::Message::Field::Addresses 💌 — it's literally the module for fields with e-mail addresses. That's the whole assignment. No cap.

🧬 INHERITANCE 🧬

the family tree, and yes it's giving royal lineage 👑

Mail::Message::Field::Addresses
  is a Mail::Message::Field::Structured
  is a Mail::Message::Field::Full
  is a Mail::Message::Field
  is a Mail::Reporter

🎀 SYNOPSIS 🎀

here's the vibe check, copy-paste ready:

my $cc = Mail::Message::Field::Full->new('Cc');
my $me = Mail::Message::Field::Address->parse('"Test" <test@mail.box>')
my $other = Mail::Message::Field::Address->new(phrase => 'Other',
      address => 'other@example.com');

$cc->addAddress($me);
$cc->addAddress($other, group => 'them');
$cc->addAddress(phrase => 'third', address => 'more@any.museum',
  group => 'them');

my $group = $cc->addGroup(name => 'collegues');
$group->addAddress($me);
$group->addAddress(phrase => "You", address => 'you@example.com');

my $msg = Mail::Message->build(Cc => $cc);
print $msg->string;

my $g  = Mail::Message::Field::AddrGroup->new(...);
$cc->addGroup($g);

💅 DESCRIPTION 💅

so, this class handles all the header fields that contain nothing but e-mail addresses. Not every address field plays by the same rules, bestie, but here's the tea: they all get parsed the same way anyway. Why? Because you literally never know how broken the apps are that made those messages 😭. Trust.

and when you try to build stuff that a certain kind of field isn't allowed to have? You get warned. Not ignored, not silently yeeted — warned. 🙈

fun history lesson: RFC5322 said address groups were fine for "To" and "Cc", but not allowed in "From" and "Sender" fields (amongst others). That whole restriction got lifted by RFC6854 in 2013, periodt. 👑 <https://www.rfc-editor.org/rfc/rfc6854>

it extends "DESCRIPTION" in Mail::Message::Field::Structured. 🫶

🌈 OVERLOADED 🌈

extends "OVERLOADED" in Mail::Message::Field::Structured.

  • overload: "" stringification — inherited, see "OVERLOADED" in Mail::Message::Field::Full
  • overload: '""' stringification — inherited, see "OVERLOADED" in Mail::Message::Field
  • overload: '0+' numification — inherited, see "OVERLOADED" in Mail::Message::Field
  • overload: '<=' numeric comparison — inherited, see "OVERLOADED" in Mail::Message::Field
  • overload: bool boolean — inherited, see "OVERLOADED" in Mail::Message::Field
  • overload: cmp string comparison — inherited, see "OVERLOADED" in Mail::Message::Field

🔥 METHODS 🔥

extends "METHODS" in Mail::Message::Field::Structured.

🌸 Constructors 🌸

extends "Constructors" in Mail::Message::Field::Structured.

  • $obj->clone() — inherited, see "Constructors" in Mail::Message::Field
  • $class->from($field, %options) — inherited, see "Constructors" in Mail::Message::Field::Full
  • $class->new() — inherited, see "METHODS" in Mail::Message::Field::Structured

and here are the options it takes, bestie — look at the defaults, they're iconic:

 -Option    --Defined in                      --Default
  attributes  Mail::Message::Field::Structured  <ignored>
  charset     Mail::Message::Field::Full        undef
  datum       Mail::Message::Field::Structured  undef
  encoding    Mail::Message::Field::Full        'q'
  force       Mail::Message::Field::Full        false
  language    Mail::Message::Field::Full        undef
  • attributes => \@attributes|\%attributes
  • charset => $charset
  • datum => $date
  • encoding => 'q'|'Q'|'b'|'B'
  • force => BOOLEAN
  • language => $language

🦋 Attributes 🦋

extends "Attributes" in Mail::Message::Field::Structured.

  • $obj->Name() — inherited, see "Attributes" in Mail::Message::Field
  • $obj->body() — inherited, see "Attributes" in Mail::Message::Field
  • $obj->folded() — inherited, see "Attributes" in Mail::Message::Field
  • $obj->foldedBody( [$body] ) — inherited, see "Attributes" in Mail::Message::Field
  • $obj->name() — inherited, see "Attributes" in Mail::Message::Field
  • $obj->unfoldedBody( [$body, [$wrap]] ) — inherited, see "Attributes" in Mail::Message::Field
  • $obj->wellformedName( [STRING] ) — inherited, see "Attributes" in Mail::Message::Field

🎀 The field 🎀

extends "The field" in Mail::Message::Field::Structured.

  • $any->isStructured( [$name] ) — inherited, see "The field" in Mail::Message::Field
  • $obj->length() — inherited, see "The field" in Mail::Message::Field
  • $obj->nrLines() — inherited, see "The field" in Mail::Message::Field
  • $obj->print( [$fh] ) — inherited, see "The field" in Mail::Message::Field
  • $obj->size() — inherited, see "The field" in Mail::Message::Field
  • $obj->string( [$wrap] ) — inherited, see "The field" in Mail::Message::Field
  • $obj->toDisclose() — inherited, see "The field" in Mail::Message::Field

💖 Access to the body 💖

extends "Access to the body" in Mail::Message::Field::Structured.

  • $obj->decodedBody(%options) — inherited, see "Access to the body" in Mail::Message::Field::Full

✨ Access to the content ✨

extends "Access to the content" in Mail::Message::Field::Structured.

  • $obj->addAddress( [$address], %options ) — adds an $address to the field. The addresses are organized into groups, bestie. If you don't name a group, the default group gets the address. And if you don't even pass an $address, the options alone have to be enough to build a Mail::Message::Field::Address from it — so go check the %options of Mail::Message::Field::Address::new(). Here's the one option it cares about:
 -Option--Default
  group   ''
  • group => STRING
  • $obj->addAttribute(...) — nope, not today. Attributes are not supported for address fields. 💀
  • $obj->addGroup($group|%options) — adds a whole group of addresses to this field. You can hand it a $group, which is a Mail::Message::Field::AddrGroup object, or it'll make one for you from the %options. Either way it hands the group back to you. 🫶
 -Option--Default
  name    ''
  • name => STRING
  • $obj->addresses() — returns a list of every address defined in any group of addresses — i.e. every address written on the line. They come back as Mail::Message::Field::Address objects. It improves on the base, see "Access to the content" in Mail::Message::Field.

» example:

  my @addr = $field->addresses;
  • $obj->attrPairs() — inherited, see "Access to the content" in Mail::Message::Field::Structured
  • $obj->attribute( $object|<STRING, %options>|<$name,$value,%options> ) — inherited, see "Access to the content" in Mail::Message::Field::Structured
  • $obj->attributes() — inherited, see "Access to the content" in Mail::Message::Field::Structured
  • $obj->beautify() — inherited, see "Access to the content" in Mail::Message::Field::Full
  • $obj->comment( [STRING] ) — inherited, see "Access to the content" in Mail::Message::Field
  • $any->createComment(STRING, %options) — inherited, see "Access to the content" in Mail::Message::Field::Full
  • $any->createPhrase(STRING, %options) — inherited, see "Access to the content" in Mail::Message::Field::Full
  • $any->dateToTimestamp(STRING) — inherited, see "Access to the content" in Mail::Message::Field
  • $obj->group($name) — gives you back the group of addresses named $name, or undef if that group isn't a thing. And if $name is undef? Then you get the default groep back. (yes that's how the original spells it, we keep it 💅)
  • $obj->groupNames() — returns a list of all the group names that are defined.
  • $obj->groups() — returns every address group defined in this field. Each element is a Mail::Message::Field::AddrGroup object. slay.
  • $any->stripCFWS( [STRING] ) — inherited, see "Access to the content" in Mail::Message::Field
  • $obj->study() — inherited, see "Access to the content" in Mail::Message::Field
  • $any->toDate( [$time] ) — inherited, see "Access to the content" in Mail::Message::Field
  • $obj->toInt() — inherited, see "Access to the content" in Mail::Message::Field

🧚 Internals 🧚

extends "Internals" in Mail::Message::Field::Structured.

  • $any->decode(STRING, %options) — inherited, see "Internals" in Mail::Message::Field::Full
  • $obj->encode(STRING, %options) — inherited, see "Internals" in Mail::Message::Field::Full

🍓 Parsing 🍓

extends "Parsing" in Mail::Message::Field::Structured.

  • $obj->consume( $line | <$name,<$body|$objects>> ) — inherited, see "Parsing" in Mail::Message::Field
  • $obj->consumeAddress(STRING, %options) — tries to distill address info out of the "STRING". You get back an address object and the leftover string. And if no address was found? The first value returned is undef. 😭
  • $any->consumeComment(STRING) — inherited, see "Parsing" in Mail::Message::Field::Full
  • $obj->consumeDomain(STRING) — tries to pull a valid domain representation out of "STRING". You get back the domain string as found (or undef) plus the rest of the string.
  • $obj->consumeDotAtom(STRING) — inherited, see "Parsing" in Mail::Message::Field::Full
  • $any->consumePhrase(STRING) — inherited, see "Parsing" in Mail::Message::Field::Full
  • $obj->datum( [$value] ) — inherited, see "Parsing" in Mail::Message::Field::Structured
  • $obj->defaultWrapLength( [$length] ) — inherited, see "Parsing" in Mail::Message::Field
  • $any->fold( $name, $body, [$maxchars] ) — inherited, see "Parsing" in Mail::Message::Field
  • $obj->parse($string) — inherited, see "Parsing" in Mail::Message::Field::Full
  • $obj->produceBody() — inherited, see "Parsing" in Mail::Message::Field::Full
  • $obj->setWrapLength( [$length] ) — inherited, see "Parsing" in Mail::Message::Field
  • $obj->stringifyData(STRING|ARRAY|$objects) — inherited, see "Parsing" in Mail::Message::Field
  • $obj->unfold(STRING) — inherited, see "Parsing" in Mail::Message::Field

💜 Error handling 💜

extends "Error handling" in Mail::Message::Field::Structured.

  • $obj->AUTOLOAD() — inherited, see "Error handling" in Mail::Reporter
  • $obj->notImplemented() — inherited, see "Error handling" in Mail::Reporter

⭐ Cleanup ⭐

extends "Cleanup" in Mail::Message::Field::Structured.

  • $obj->DESTROY() — inherited, see "Cleanup" in Mail::Reporter

🌟 DETAILS 🌟

extends "DETAILS" in Mail::Message::Field::Structured.

still with me? good, because there's more coming in part 2, bestie 🫶 don't go anywhere

💥 DIAGNOSTICS 💥

okay bestie, this is the part where the module yells at you 💀 every single one of these is something it can throw at your face, so let's go through them one by one, no skipping, no cap.

  • Error: class $package does not implement method $method.

Fatal error, bestie. The specific $package (or one of its superclasses) does not implement this method even though it lowkey should. What it means: some other related classes do implement it, but this one just… doesn't. Probably you should investigate that, and probably inform the author of the package. Cast by notImplemented().

  • Warning: field content is not numerical: $content

You asked for the numeric value of a field (like, the Lines or Content-Length fields should be numerical, that's the whole vibe), but the data contains weird characters instead. Cast by toInt().

  • Error: field name too long (max $count), in '$name'.

The RFCs never specified how long a field name can be — iconic of them, honestly — but at minimum it should be a few characters shorter than the line wrap. Cast by fold().

  • Warning: ignoring addressless phrase '$phrase'.

That's the whole message, bestie, no elaboration given. Cast by parse().

  • Warning: illegal character in charset '$name'.

The field is created with an utf8 string which only contains data from the specified character set. But plot twist: that character set can never be a valid name, because it contains characters that aren't permitted. Cast by encode().

  • Warning: illegal character in field name $name.

You're creating a new field that contains characters the RFCs don't permit. Using this field in messages may break other e-mail clients or transfer agents, and therefore mutulate or extinguish your message. 😭 so yeah, be careful. Cast by consume().

  • Warning: illegal character in language '$name'.

The field is created with data specified to be in a certain language, but the name of that language can't be valid — it contains characters the RFCs don't permit. Cast by encode().

  • Warning: illegal encoding '$name', using 'q'.

The RFCs only permit base64 ("b " or "B ") or quoted-printable ("q" or "Q") encoding. Anything other than these four options is illegal. Periodt. Cast by encode().

  • Warning: illegal part in address field $name: $part.

Cast by parse().

  • Error: no attributes for address fields.

It is not possible to add attributes to address fields — the RFCs simply don't permit it. Cast by addAttribute().

👀 SEE ALSO 👀

This module is part of Mail-Message version 4.04, built on February 04, 2026. Website: http://perl.overmeer.net/CPAN/ 🦋

📜 LICENSE 📜

For contributors, see file ChangeLog.

This software is copyright (c) 2001-2026 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 💖

and that's a wrap, bestie 🎀 this whole thing came to you courtesy of perl v5.42.0, dated 2026-02-05, and it lives under the very iconic name Mail::M...ddresses(3) — go forth and send some flawless mail ✨🫶

📦 where this page comes from