mail.headers

import mail.headers

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.headers.* needs import mail.headers.

The header block of a message: what is in it, in what order, and how it is written back out.

Mail headers are not a dictionary. The same name can appear more than once and the order matters, which is why Received traces a route and why a signature covers the headers it covers. Headers keeps them as they were, matches names without regard to case, and hands back one value or all of them as the caller asks.

import mail.headers { Headers }

var headers = Headers()

headers.set('Subject', 'Quarterly report')
headers.add('Received', 'from a.example.com')
headers.add('Received', 'from b.example.com')

echo headers.get('subject', nil)
echo headers.get_all('Received').length()

Quarterly report
2

Constants

LINE_WIDTH

mail.headers.LINE_WIDTH = 78

ADDRESS_HEADERS

mail.headers.ADDRESS_HEADERS = [...]

Functions

unfold()

mail.headers.unfold(text: string)

fold()

mail.headers.fold(name: string, value: string, width: ?number) -> string

Writes one header, folded so that no line runs past the width.

Folding happens at whitespace, which is the only place it is allowed to. A single run of characters with no whitespace in it cannot be folded and is left to overrun, because breaking it would change what it says.

import mail.headers

var folded = headers.fold('Subject', ('word ' * 20).trim(), 40)

echo folded.lines().length()

3

Parameters

• name (string)
• value (string)
• width (?number) — 78 when not given.

Returns string — with \r\n between the lines it produced

Classes

Headers

class mail.Headers

The headers of a message or of one of its parts.

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

Constructor

mail.Headers(entries: ?list)

Parameters

• entries (?list) — Pairs of [name, value] to start with.

Headers.parse()

mail.Headers.parse(text) -> Headers

Reads a header block.

Lines that continue the one before them are joined back together. A line that is not a header and does not continue one is skipped, which is what lets a message with an mbox separator in front of it still be read.

Parameters

• text (string|bytes) — The block, without the blank line that ends it.

Returns Headers

Headers.add()

mail.Headers.add(name: string, value) -> Headers

Adds a header, leaving any already there alone.

Parameters

• name (string)
• value (string)

Returns Headers — itself.

Headers.prepend()

mail.Headers.prepend(name: string, value) -> Headers

Adds a header in front of every other one.

A header that records what happened to a message on its way goes at the top, so that reading down the block reads backwards through the message’s history. Received and DKIM-Signature are both added this way.

Parameters

• name (string)
• value (string)

Returns Headers — itself.

Headers.set()

mail.Headers.set(name: string, value) -> Headers

Sets a header, removing any already there.

Parameters

• name (string)
• value (string)

Returns Headers — itself.

Headers.get()

mail.Headers.get(name: string, fallback) -> string|any

The first value of a header, or fallback when it is not there.

The value comes back as it was written. Use decoded() when it may carry encoded words.

Parameters

• name (string)
• fallback (?any)

Returns string|any

Headers.get_all()

mail.Headers.get_all(name: string) -> list

Every value of a header, in the order they appear.

Parameters

• name (string)

Returns list — of string

Headers.decoded()

mail.Headers.decoded(name: string, fallback) -> string|any

The first value of a header with its encoded words decoded.

Parameters

• name (string)
• fallback (?any)

Returns string|any

Headers.remove()

mail.Headers.remove(name: string) -> number

Removes every instance of a header.

Parameters

• name (string)

Returns number — how many were removed.

Headers.contains()

mail.Headers.contains(name: string) -> bool

Whether a header is present.

Parameters

• name (string)

Returns bool

Headers.names()

mail.Headers.names() -> list

The names of every header, in order and as they were written. A name that appears more than once appears here more than once.

Returns list — of string

Headers.entries()

mail.Headers.entries() -> list

Every header as a { name, value } dictionary, in order.

Returns list — of dict

Headers.length()

mail.Headers.length() -> number

How many headers there are, counting repeats separately.

Returns number

Headers.is_empty()

mail.Headers.is_empty() -> bool

Returns bool

Headers.clone()

mail.Headers.clone() -> Headers

A copy that can be changed without changing this one.

Returns Headers

Headers.addresses()

mail.Headers.addresses(name: string) -> list

The addresses in a header, across every instance of it.

import mail.headers { Headers }

var headers = Headers([['To', 'Ann <ann@example.com>, bob@example.com']])

echo headers.addresses('to').map(@(person) => person.address)

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

Parameters

• name (string)

Returns list — of Address

Headers.set_addresses()

mail.Headers.set_addresses(name: string, people) -> Headers

Sets a header to a list of addresses.

Parameters

• name (string)
• people (list|string|Address) — One address or several, as Address values or as text to be parsed.

Returns Headers — itself.

Headers.date()

mail.Headers.date(name: ?string) -> Date|nil

A header read as a date, or nil when it is absent or unreadable.

Parameters

• name (?string) — Date when not given.

Returns Date|nil

Headers.set_date()

mail.Headers.set_date(name: string, moment) -> Headers

Sets a header to a date, written the way RFC 5322 wants one.

Parameters

• name (string)
• moment (?Date) — The current time when not given.

Returns Headers — itself.

Headers.content_type()

mail.Headers.content_type() -> ContentType

The Content-Type of this part.

Returns ContentType

Headers.content_disposition()

mail.Headers.content_disposition() -> ContentDisposition

The Content-Disposition of this part.

Returns ContentDisposition

Headers.to_string()

mail.Headers.to_string() -> string

The whole block, folded, with every line ended by a carriage return and newline. The blank line that separates the headers from the body is not included.

Returns string

2026, Richard Ore and Zuri contributors