--- name: "Mail::Message::Field::Addresses" section: "3pm" platform: "linux" package: "perl-mail-message" version: "4.05-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Mail::Message::Field::Addresses" --- # Mail::Message::Field::Addresses(3pm) Fields with e-mail addresses ## NAME Mail::Message::Field::Addresses - Fields with e-mail addresses ## INHERITANCE ``` 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 ``` my $cc = Mail::Message::Field::Full->new('Cc'); my $me = Mail::Message::Field::Address->parse('"Test" ') 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 All header fields which contain e-mail addresses only. Not all address fields have the same possibilities, but they are all parsed the same: you never know how broken the applications are which produce those messages. When you try to create constructs which are not allowed for a certain kind of field, you will be warned. RFC5322 did allow address groups for "To" and "Cc", but not to be used in (amongst other) "From" and "Sender" fields. This restriction got lifted by RFC6854 (2013). \ 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 ``` -Option --Defined in --Default attributes Mail::Message::Field::Structured 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 ) Add an `$address` to the field. The addresses are organized in groups. If no group is specified, the default group is taken to store the address in. If no `$address` is specified, the option must be sufficient to create a Mail::Message::Field::Address from. See the `%options` of **Mail::Message::Field::Address::new()**. ``` -Option--Default group '' ``` - group =\> STRING - $obj-\>**addAttribute**(...) Attributes are not supported for address fields. - $obj-\>**addGroup**($group\|%options) Add a group of addresses to this field. A `$group` can be specified, which is a Mail::Message::Field::AddrGroup object, or one is created for you using the `%options`. The group is returned. ``` -Option--Default name '' ``` - name =\> STRING - $obj-\>**addresses**() Returns a list with all addresses defined in any group of addresses: all addresses which are specified on the line. The addresses are Mail::Message::Field::Address objects. Improves 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\|\\|\<$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) Returns the group of addresses with the specified `$name`, or `"undef"` if it does not exist. If `$name` is `"undef"`, then the default groep is returned. - $obj-\>**groupNames**() Returns a list with all group names which are defined. - $obj-\>**groups**() Returns all address groups which are defined in this field. Each element is a Mail::Message::Field::AddrGroup object. - $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) Try to destilate address information from the `"STRING"`. Returned are an address **object** and the left-over string. If no address was found, the first returned value is `"undef"`. - $any-\>**consumeComment**(STRING) Inherited, see "Parsing" in Mail::Message::Field::Full - $obj-\>**consumeDomain**(STRING) Try to get a valid domain representation from `"STRING"`. Returned are the domain string as found (or `"undef"`) and 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. ## DIAGNOSTICS - Error: class $package does not implement method $method. Fatal error: the specific `$package` (or one of its superclasses) does not implement this method where it should. This message means that some other related classes do implement this method however the class at hand does not. Probably you should investigate this and probably inform the author of the package. Cast by `notImplemented()` - Warning: field content is not numerical: $content The numeric value of a field is requested (for instance the `"Lines"` or `"Content-Length"` fields should be numerical), however the data contains weird characters. Cast by `toInt()` - Error: field name too long (max $count), in '$name'. It is not specified in the RFCs how long a field name can be, but at least it should be a few characters shorter than the line wrap. Cast by `fold()` - Warning: ignoring addressless phrase '$phrase'. 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. However, that character set can never be a valid name because it contains characters which are not permitted. Cast by `encode()` - Warning: illegal character in field name $name. A new field is being created which does contain characters not permitted by the RFCs. Using this field in messages may break other e-mail clients or transfer agents, and therefore mutulate or extinguish your message. Cast by `consume()` - Warning: illegal character in language '$name'. The field is created with data which is specified to be in a certain language, however, the name of the language cannot be valid: it contains characters which are not permitted by the RFCs. Cast by `encode()` - Warning: illegal encoding '$name', using 'q'. The RFCs only permit base64 (`"b "` or `"B "`) or quoted-printable (`"q"` or `"Q"`) encoding. Other than these four options are illegal. Cast by `encode()` - Warning: illegal part in address field $name: $part. Cast by `parse()` - Error: no attributes for address fields. Is is not possible to add attributes to address fields: it is not permitted by the RFCs. Cast by `addAttribute()` ## SEE ALSO This module is part of Mail-Message version 4.05, built on April 10, 2026. Website: *http://perl.overmeer.net/mailbox/* ## 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.