mail.errors

import mail

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

Every error the mail stack raises, under one root.

MailError is that root. The subclasses separate the cases worth handling differently: a message that will not parse, a server that refused, credentials that were not accepted, a connection that went away mid-conversation.

The protocols each add one of their own, carrying the reply the server actually sent. SMTP splits its into two, because the difference between “not now” and “not ever” is the difference between queueing a message and bouncing it.

Classes

MailError

class mail.MailError < Error

Base class for every error this module raises.

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

MailError.to_string()

mail.MailError.to_string()

MessageError

class mail.MessageError < MailError

The bytes handed over are not a message, or are one that contradicts itself: a header with no colon in it, a multipart body whose boundary never appears, a transfer encoding that decodes to nothing.

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

MessageError.to_string()

mail.MessageError.to_string()

ProtocolError

class mail.ProtocolError < MailError

The server said something the protocol does not allow: a greeting that is not a greeting, a response with no tag, a line longer than the specification permits.

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

ProtocolError.to_string()

mail.ProtocolError.to_string()

ConnectionClosed

class mail.ConnectionClosed < MailError

The connection closed while a conversation was still going on, or a command was issued on one that had already closed.

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

ConnectionClosed.to_string()

mail.ConnectionClosed.to_string()

AuthenticationError

class mail.AuthenticationError < MailError

The credentials were not accepted, or no mechanism both ends understand was on offer.

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

AuthenticationError.to_string()

mail.AuthenticationError.to_string()

StateError

class mail.StateError < MailError

A command was issued that makes no sense in the state the connection is in: a fetch before a mailbox has been selected, a recipient before a sender.

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

StateError.to_string()

mail.StateError.to_string()

SmtpError

class mail.SmtpError < MailError

The server rejected a command, and said so with a reply code.

code is the three digit code, and enhanced the finer grained one from RFC 3463 when the server sends one, as '5.7.1'. Servers differ in how much detail they put in text, and none of it is meant to be matched on.

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

Constructor

mail.SmtpError(message: string, code: number, enhanced: ?string, lines: ?list)

Parameters

• message (string)
• code (number) — The three digit reply code.
• enhanced (?string) — The enhanced status code, when sent.
• lines (?list) — Every line of the reply, without its code.

SmtpError.to_string()

mail.SmtpError.to_string()

SmtpTransientError

class mail.SmtpTransientError < SmtpError

A 4xx reply: the server could not accept the message now, and the sender should try again later. A queue retries these.

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

SmtpTransientError.to_string()

mail.SmtpTransientError.to_string()

SmtpPermanentError

class mail.SmtpPermanentError < SmtpError

A 5xx reply: the server will not accept the message, and trying again changes nothing. A queue bounces these.

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

SmtpPermanentError.to_string()

mail.SmtpPermanentError.to_string()

ImapError

class mail.ImapError < MailError

The IMAP server answered a command with NO or BAD.

status is which of the two it was. NO means the command was understood and refused; BAD means it was not understood, which points at the client rather than the request.

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

Constructor

mail.ImapError(message: string, status: string, code: ?string)

Parameters

• message (string)
• status (string) — NO or BAD.
• code (?string) — The bracketed response code, such as TRYCREATE, when the server sent one.

ImapError.to_string()

mail.ImapError.to_string()

Pop3Error

class mail.Pop3Error < MailError

The POP3 server answered a command with -ERR.

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

Pop3Error.to_string()

mail.Pop3Error.to_string()

MailboxError

class mail.MailboxError < MailError

Something went wrong in a mail store: a mailbox that does not exist, one that cannot be created, a message that has gone from under a session that was reading it.

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

MailboxError.to_string()

mail.MailboxError.to_string()

2026, Richard Ore and Zuri contributors