mail

import mail

Mail, from the message to the socket.

mail builds and reads messages, and speaks the three protocols that move them: SMTP to send, IMAP and POP3 to read. It also runs the other end, with an SMTP server that accepts mail and an IMAP server that serves it. All of it is written in Zuri.

import mail

var note = mail.message()
  .set_from('reports@example.com')
  .add_to('ann@example.com')
  .set_subject('Quarterly report')
  .set_text('The numbers are in.')

mail.send('smtp://mail.example.com', note, {
  username: 'reports',
  password: secret,
})

What is here

Reading mail

import mail

var inbox = mail.imap('imaps://mail.example.com', {
  username: 'ann',
  password: secret,
})

inbox.select('INBOX')

for id in inbox.search('UNSEEN') {
  echo inbox.fetch_message(id).subject()
}

inbox.logout()

Running a server

The servers are the same shape as http.HttpServer: bind, listen, and hand each connection to a worker. An SmtpServer decides what to accept through handlers, and an ImapServer answers from a MailStore, of which two ship: one on disk in Maildir format and one in memory.

Security

Every client can start in TLS or negotiate it with STARTTLS, and refuses to send credentials over a connection that is neither. mail.dkim signs outgoing mail and verifies incoming mail.

The mail API

Every public name in mail, wherever it is declared. Each links to the page that documents it.

Submodules

Functions

parse_address()

mail.parse_address(text: string) -> Address

Reads one address out of text.

import mail

echo mail.parse_address('Ann <ann@example.com>').address

ann@example.com

Parameters

• text (string)

Returns Address

Raises MessageError if the text holds no address, or several.

parse_address_list()

mail.parse_address_list(text: string) -> list

Reads every address out of text, with any groups flattened into their members.

Parameters

• text (string)

Returns list — of Address

parse_address_groups()

mail.parse_address_groups(text: string) -> list

Reads every address out of text, keeping the groups as groups.

Parameters

• text (string)

Returns list — of Address and Group

format_addresses()

mail.format_addresses(people: list) -> string

Writes a list of addresses as a header value.

Parameters

• people (list) — Address values, Group values, or text to be parsed first.

Returns string

send()

mail.send(url: string, note, options: ?dict) -> Reply

Sends one message, opening the connection and closing it again.

This is the whole of sending mail for a program that sends one at a time. A program sending many wants an SmtpClient of its own, kept open across all of them.

import mail

mail.send('smtp://mail.example.com', mail.message()
  .set_from('reports@example.com')
  .add_to('ann@example.com')
  .set_subject('Quarterly report')
  .set_text('The numbers are in.'),
  { username: 'reports', password: secret })

Parameters

• url (string) — smtp://host or smtps://host.
• note (Message)
• options (?dict) — Everything SmtpClient.connect() takes, and from and to to override the envelope.

Returns Reply — the server’s verdict on the message.

Raises SmtpError if the server refuses any part of it.

smtp()

mail.smtp(url: string, options: ?dict) -> SmtpClient

Opens a connection to a server that sends mail.

Parameters

• url (string)
• options (?dict)

Returns SmtpClient

imap()

mail.imap(url: string, options: ?dict) -> ImapClient

Opens a connection to a server that stores mail.

Parameters

• url (string)
• options (?dict)

Returns ImapClient

pop3()

mail.pop3(url: string, options: ?dict) -> Pop3Client

Opens a connection to a server that hands mail over.

Parameters

• url (string)
• options (?dict)

Returns Pop3Client

2026, Richard Ore and Zuri contributors