--- name: "Mail::Message::Field::Address" 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::Address" --- # Mail::Message::Field::Address(3pm) One e-mail address ## NAME Mail::Message::Field::Address - One e-mail address ## INHERITANCE ``` Mail::Message::Field::Address is a Mail::Identity is a User::Identity::Item ``` ## SYNOPSIS ``` my $addr = Mail::Message::Field::Address->new(...); my $ui = User::Identity->new(...); my $addr = Mail::Message::Field::Address->coerce($ui); my $mi = Mail::Identity->new(...); my $addr = Mail::Message::Field::Address->coerce($mi); print $addr->address; print $addr->fullName; # possibly unicode! print $addr->domain; ``` ## DESCRIPTION Many header fields can contain e-mail addresses. Each e-mail address can be represented by an object of this class. These objects will handle interpretation and character set encoding and decoding for you. Extends "DESCRIPTION" in Mail::Identity. ## OVERLOADED - overload: **'""'** stringification When the object is used in string context, it will return the encoded representation of the e-mail address, just like **string()** does. - overload: **'bool'** use as boolean The object used as boolean will always return `"true"` - overload: **'cmp'** string comparison Two address objects are the same when their email addresses are the same. ## METHODS Extends "METHODS" in Mail::Identity. ### Constructors Extends "Constructors" in Mail::Identity. - $obj-\>**coerce**( \, %options ) Try to coerce the `$object` into a `"Mail::Message::Field::Address"`. In case of a `"STRING"`, it is interpreted as an email address. The `%options` are passed to the object creation, and overrule the values found in the `$object`. The result may be `"undef"` or a newly created object. If the `$object` is already of the correct type, it is returned unmodified. The `$object` may currently be a Mail::Address, a Mail::Identity, or a User::Identity. In case of the latter, one of the user's addresses is chosen at random. - $class-\>**new**( \[$name\], %options ) Inherited, see "Constructors" in Mail::Identity - $obj-\>**parse**(STRING) Parse the string for an address. You never know whether one or more addresses are specified on a line (often applications are wrong), therefore, the `"STRING"` is first parsed for as many addresses as possible and then the one is taken at random. ### Attributes Extends "Attributes" in Mail::Identity. - $obj-\>**address**() Inherited, see "Attributes" in Mail::Identity - $obj-\>**charset**() Inherited, see "Attributes" in Mail::Identity - $obj-\>**comment**( \[STRING\] ) Inherited, see "Attributes" in Mail::Identity - $obj-\>**description**() Inherited, see "Attributes" in User::Identity::Item - $obj-\>**domain**() Inherited, see "Attributes" in Mail::Identity - $obj-\>**language**() Inherited, see "Attributes" in Mail::Identity - $obj-\>**location**() Inherited, see "Attributes" in Mail::Identity - $obj-\>**name**( \[$newname\] ) Inherited, see "Attributes" in User::Identity::Item - $obj-\>**organization**() Inherited, see "Attributes" in Mail::Identity - $obj-\>**phrase**() Inherited, see "Attributes" in Mail::Identity - $obj-\>**username**() Inherited, see "Attributes" in Mail::Identity ### Collections Extends "Collections" in Mail::Identity. - $obj-\>**add**($collection, $role) Inherited, see "Collections" in User::Identity::Item - $obj-\>**addCollection**( $object \| \<\[$type\], %options\> ) Inherited, see "Collections" in User::Identity::Item - $obj-\>**collection**($name) Inherited, see "Collections" in User::Identity::Item - $obj-\>**parent**( \[$parent\] ) Inherited, see "Collections" in User::Identity::Item - $obj-\>**removeCollection**($object\|$name) Inherited, see "Collections" in User::Identity::Item - $any-\>**type**() Inherited, see "Collections" in User::Identity::Item - $obj-\>**user**() Inherited, see "Collections" in User::Identity::Item ### Searching Extends "Searching" in Mail::Identity. - $obj-\>**find**($collection, $role) Inherited, see "Searching" in User::Identity::Item ### Accessors - $obj-\>**encoding**() Character-set encoding, like 'q' and 'b', to be used when non-ascii characters are to be transmitted. ### Access to the content - $obj-\>**string**() Returns an RFC compliant e-mail address, which will have character set encoding if needed. The objects are also overloaded to call this method in string context. ยป example: ``` print $address->string; print $address; # via overloading ``` ## DIAGNOSTICS - Error: cannot coerce a $type into a $class When addresses are specified to be included in header fields, they may be coerced into Mail::Message::Field::Address objects first. What you specify is not accepted as address specification. This may be an internal error. Cast by `coerce()` - Error: cannot load collection module for $type ($class): $@ Either the specified `$type` does not exist, or that module named `$class` returns compilation errors. If the type as specified in the warning is not the name of a package, you specified a nickname which was not defined. Maybe you forgot the 'require' the package which defines the nickname. Cast by `addCollection()` - Error: invalid collection $name. The collection with `$name` does not exist and can not be created. Cast by `add()` - Error: this $object is not a collection. Cast by `addCollection()` ## 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.