Skip to content

xtr_mailer.exception

The errors the mailer raises, every one a :class:MailerError.

HttpTransportError

HttpTransportError(message: str, response: HttpResponseInterface, code: int = 0)

Bases: TransportError

A provider's API answered an email with a refusal.

It carries the response, so a caller can read what the provider said beyond the message.

Attributes:

Record why the provider refused the email and what it answered.

Parameters:

  • message (str) –

    Why the send failed, in the provider's words where it gave any.

  • response (HttpResponseInterface) –

    What the provider answered with.

  • code (int, default: 0 ) –

    The status the provider answered with, 0 when not given.

IncompleteDsnError

Bases: InvalidArgumentError

A DSN parses, but lacks a part its transport cannot work without — a user, a password.

The message names the missing part only, never the DSN, which carries credentials.

InvalidArgumentError

Bases: MailerError, ValueError

A value handed to this library cannot be used: a malformed DSN, an envelope with no sender.

Also a :class:ValueError, so code that already guards against a bad value catches it without knowing this library exists.

LogicError

Bases: MailerError, RuntimeError

This library was used in a way that cannot work, whatever the email carries.

A DSN scheme no installed factory serves, a transport handed an email it was never built for: each is a mistake in the code or the configuration, so retrying it changes nothing.

MailerError

Bases: Exception

Something an email could not be sent through — catch this to catch them all.

MailerRuntimeError

Bases: MailerError, RuntimeError

Something an email depends on failed while it was sent — a server, a process.

The input was fine and the code is fine; the world did not cooperate. Raising one out of a message handler is what makes a message bus retry the send.

TransportError

TransportError(message: str, code: int = 0)

Bases: MailerRuntimeError

A server could not be reached, or refused an email.

It is the one error a round-robin or failover transport takes as a sign that a transport is down: anything else is a mistake that another transport would make too.

Attributes:

  • code (int) –

    The reply code the server refused with — an SMTP reply code, an HTTP status — or 0 when there was none. SMTP transports tell a refusal from a dropped connection by it.

  • debug (str) –

    The protocol transcript up to the failure, so a caller can see what was said. Authentication exchanges are kept out of it: it never carries credentials.

Record why the email could not be handed over.

Parameters:

  • message (str) –

    Why the transport failed.

  • code (int, default: 0 ) –

    The reply code the server refused with, 0 when there was none.

append_debug

append_debug(debug: str) -> None

Add debug to the transcript.

The error is raised from deep inside a transport, which only knows its own part of the exchange; each layer it passes through appends what it saw.

UnexpectedResponseError

UnexpectedResponseError(message: str, code: int = 0)

Bases: TransportError

An SMTP server replied to a command with a code the command does not accept.

Its :attr:code is the reply code the server sent: an SMTP transport resets the session after a refusal, but not after 421, the server closing the connection, and authentication tries the next mechanism after one.

UnsupportedSchemeError

UnsupportedSchemeError(scheme: str, name: str | None = None, supported: Sequence[str] = ())

Bases: LogicError

No factory serves a DSN's scheme.

The common cause is a provider library that is not installed, so a scheme a first-party provider library serves is answered with the command that installs it — this package's extra named after the provider, quoted so a shell does not read its brackets. Any other scheme is answered with the schemes that are supported, when the caller knows them. The message names the scheme only: never the DSN, which carries credentials — and shows it escaped and cut short, as it is whatever the application's configuration says.

Attributes:

  • scheme (str) –

    The scheme no factory serves.

  • name (str | None) –

    The mailer transport that was being built, or None.

  • supported (tuple[str, ...]) –

    The schemes that are supported there.

Explain why scheme has no transport.

Takes the scheme rather than the DSN, so nothing that carries credentials ever reaches an error.

Parameters:

  • scheme (str) –

    The scheme of the DSN no factory serves.

  • name (str | None, default: None ) –

    The transport being built, named in the message with supported.

  • supported (Sequence[str], default: () ) –

    The schemes that are supported there.