mail.address

import mail.address

mail lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled mail.address.* needs import mail.address.

Reading and writing the addresses in a mail header.

An address in a header is rarely just an address. It can carry a display name, the name can be quoted or encoded, either can have comments buried in it, and a header can list several of them or gather them into a named group. This module turns all of that into Address objects, and turns them back into a header a server will accept.

import mail.address

var who = address.parse('"Ore, Richard" <richard@example.com> (author)')

echo who.name
echo who.address
echo who.domain

Ore, Richard
richard@example.com
example.com

Functions

parse_groups()

mail.address.parse_groups(text: string) -> list

Reads every address in a header value, keeping the groups.

Entries that are not addresses at all are left out rather than raising, because one unusable entry in a To header is no reason to refuse the whole message.

Parameters

• text (string)

Returns list — of Address and Group

parse_list()

mail.address.parse_list(text: string) -> list

Reads every address in a header value.

A group’s members come back alongside the rest, since a program sending mail cares who the recipients are and not how they were gathered.

import mail.address

var people = address.parse_list('Ann <ann@example.com>, bob@example.com')

echo people.map(@(person) => person.address)

[ann@example.com, bob@example.com]

Parameters

• text (string)

Returns list — of Address

parse()

mail.address.parse(text: string) -> Address

Reads exactly one address.

Parameters

• text (string)

Returns Address

Raises MessageError if text holds no address, or more than one.

address()

mail.address.address(spec: string, name: ?string) -> Address

Builds an address without parsing anything.

Parameters

• spec (string) — The address, as local@domain.
• name (?string) — The display name.

Returns Address

format_list()

mail.address.format_list(items: list) -> string

Writes a list of addresses as a header value.

Parameters

• items (list) — Address or Group values, or plain strings, which are parsed first.

Returns string

Classes

Address

class mail.Address

One address, with the display name that was written alongside it.

name is the display name, already decoded from whatever encoding the header carried it in, and is an empty string when there was none. address is the address itself, local the part before the @ and domain the part after it.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

mail.Address(spec: string, name: ?string)

Builds an address.

import mail.address { Address }

echo Address('richard@example.com', 'Richard Ore').to_string()

Richard Ore <richard@example.com>

Parameters

• spec (string) — The address, as local@domain.
• name (?string) — The display name. Empty when not given.

Raises MessageError if spec has no local part.

Address.is_routable()

mail.Address.is_routable() -> bool

Whether this address has a domain. An address without one is legal in a header but cannot be delivered to over the network.

Returns bool

Address.to_string()

mail.Address.to_string() -> string

The address as a header would carry it, with the display name quoted or encoded as it needs to be.

Returns string

Address.equals()

mail.Address.equals(other) -> bool

Whether two addresses are the same one.

The domain is compared without regard to case, since domains are case-insensitive. The local part is compared exactly, since it is the receiving server’s to interpret and some of them do distinguish case.

Parameters

• other (Address)

Returns bool

Group

class mail.Group

A named group of addresses, as Managers: ann@example.com, bob@example.com; writes one.

Groups are rare, and a program that does not care about them can use parse_list(), which hands back the members and forgets the name.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

mail.Group(name: string, members: list)

Parameters

• name (string) — The group’s name.
• members (list) — The Address values in it, possibly empty.

Group.to_string()

mail.Group.to_string()

2026, Richard Ore and Zuri contributors