`mail.pop3.client`

import mail

Everything here is re-exported by mail, so import mail is enough and the names are called as mail.*. Importing mail.pop3.client on its own works too and reaches the same definitions.

POP3: collecting mail and taking it away.

Where IMAP leaves mail on the server and lets a client work with it in place, POP3 hands it over and, usually, forgets it. That makes it the wrong protocol for reading mail on more than one device and the right one for a program whose job is to drain a mailbox.

import mail.pop3 { Pop3Client }

var mailbox = Pop3Client.connect('pop3s://mail.example.com', {
  username: 'ann',
  password: secret,
})

for entry in mailbox.list() {
  var note = mailbox.retrieve(entry.number)

  archive(note)
  mailbox.delete(entry.number)
}

mailbox.quit()

Nothing is actually removed until quit(): delete() only marks, and reset() undoes every mark. A connection that drops without quit() leaves the mailbox as it was, which is the protocol protecting against a client that fails halfway.

There is no POP3 server here. A POP3 server is an IMAP server with almost everything taken away, and mail.imap is the one to run.

Constants

`POP3_SCHEMES`

mail.POP3_SCHEMES = {...}

Classes

`Entry`

class mail.Entry

One message in the mailbox, as list() reports it.

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

Constructor

mail.Entry(number: number, size: number, uid: ?string)

Parameters

number (number) — Its position, which holds for this session only.
size (number) — How many bytes it is.
uid (?string) — The identifier that outlives the session, when the server offers one.

`Entry.to_string()`

mail.Entry.to_string()

`Pop3Client`

class mail.Pop3Client

A connection to a server that hands mail over.

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

Constructor

mail.Pop3Client(connection, options: ?dict)

Builds a client around a connection that is already open.

Parameters

connection (LineStream)
options (?dict) — As connect().

`Pop3Client.connect()`

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

Opens a connection and authenticates.

option	default	what it does
`username`, `password`	none	authenticate when both are given
`tls`	`require`	`require`, `prefer` or `disable`, when not already encrypted
`tls_config`	a default one	the trust settings for TLS
`mechanisms`	all of them	restricts which are acceptable
`timeout`	`60000`	milliseconds to wait on the socket

Parameters

url (string) — pop3s://host, pop3://host, or a bare host.
options (?dict)

Returns Pop3Client

Raises Pop3Error if the server refuses.

Raises AuthenticationError if it refuses the credentials.

`Pop3Client.begin()`

mail.Pop3Client.begin() -> Pop3Client

Reads the greeting, negotiates TLS and authenticates.

Returns Pop3Client — itself.

`Pop3Client.supports()`

mail.Pop3Client.supports(name: string) -> bool

Whether the server offers a capability.

Parameters

name (string)

Returns bool

`Pop3Client.is_secure()`

mail.Pop3Client.is_secure() -> bool

Whether the connection is encrypted.

Returns bool

`Pop3Client.refresh_capabilities()`

mail.Pop3Client.refresh_capabilities() -> list

Asks the server what it can do.

A server old enough not to know CAPA reports nothing, which is not an error: it simply predates the command.

Returns list — of string

`Pop3Client.start_tls()`

mail.Pop3Client.start_tls() -> Pop3Client

Negotiates TLS over a connection that started in the clear.

Returns Pop3Client — itself.

Raises Pop3Error if the server refuses.

`Pop3Client.login()`

mail.Pop3Client.login(mechanism: ?string) -> Pop3Client

Authenticates, choosing the strongest mechanism both ends know.

APOP is preferred over sending the password where the server’s greeting offered it, and USER/PASS is the last resort and only over TLS.

Parameters

mechanism (?string) — Forces one rather than choosing.

Returns Pop3Client — itself.

Raises AuthenticationError if the credentials are refused or nothing usable is on offer.

`Pop3Client.authenticate()`

mail.Pop3Client.authenticate(mechanism) -> Pop3Client

Runs one authentication exchange with a mechanism already built.

Parameters

mechanism (Mechanism)

Returns Pop3Client — itself.

Raises AuthenticationError if the server refuses.

`Pop3Client.stat()`

mail.Pop3Client.stat() -> dict

How many messages are waiting and how large they are together.

Returns dict — of count and size.

`Pop3Client.list()`

mail.Pop3Client.list() -> list

Every message waiting, with its size and, where the server offers one, its lasting identifier.

The number is only good for this session: deleting a message renumbers the rest on the next connection. The identifier is what a program that runs twice should remember.

Returns list — of Entry

`Pop3Client.uidl()`

mail.Pop3Client.uidl()

The lasting identifier of every message, by its number in this session.

Returns — dict, empty when the server does not offer UIDL.

`Pop3Client.retrieve()`

mail.Pop3Client.retrieve(number: number) -> Message

Fetches one message whole.

Parameters

number (number)

Returns Message

Raises Pop3Error if there is no such message.

`Pop3Client.retrieve_raw()`

mail.Pop3Client.retrieve_raw(number: number) -> bytes

Fetches one message as it arrived, without parsing it.

Parameters

number (number)

Returns bytes

Raises Pop3Error if there is no such message.

`Pop3Client.top()`

mail.Pop3Client.top(number: number, lines: ?number) -> Message

Fetches a message’s headers and the first few lines of its body, which is enough to decide whether to fetch the rest.

Parameters

number (number)
lines (?number) — Body lines to include. None when not given.

Returns Message

Raises Pop3Error if the server does not offer TOP.

`Pop3Client.delete()`

mail.Pop3Client.delete(number: number) -> Pop3Client

Marks a message for removal. Nothing goes until quit().

Parameters

number (number)

Returns Pop3Client — itself.

Raises Pop3Error if there is no such message.

`Pop3Client.reset()`

mail.Pop3Client.reset() -> Pop3Client

Unmarks everything marked for removal in this session.

Returns Pop3Client — itself.

`Pop3Client.noop()`

mail.Pop3Client.noop() -> Pop3Client

Asks the server for nothing, which keeps the connection alive.

Returns Pop3Client — itself.

`Pop3Client.quit()`

mail.Pop3Client.quit() -> Pop3Client

Says goodbye, which is when the server actually removes whatever was marked, and closes the connection.

Returns Pop3Client — itself.

`Pop3Client.close()`

mail.Pop3Client.close() -> Pop3Client

Closes the connection without saying goodbye, which leaves the mailbox exactly as it was.

Returns Pop3Client — itself.

`Pop3Client.to_string()`

mail.Pop3Client.to_string()

2026, Richard Ore and Zuri contributors

Keyboard shortcuts

The Zuri Standard Library