SMTPBackend

An SMTP backend submits each message to an SMTP server through smtplib.

Usage

Source

SMTPBackend(
    host, *, port=587, security="starttls", from_address, credential=None
)

connect() opens the socket, starts TLS unless security is "none", and authenticates. So a wrong password or a rejected token raises AuthenticationError on that line. Every socket operation times out after 60 seconds, and no setting changes it. See ADR-0005 and ADR-0017.

A server may refuse some recipients and accept the rest. The send then returns normally with the refusals in SendResult.refused, so a caller who ignores the send result loses them. See ADR-0004.

There is no size pre-check. smtplib sends the message size to a server that advertises SIZE, and the server’s 552 raises RejectedError. See ADR-0019.

Parameters

host: str

The server’s host name. TLS checks the server’s certificate against it.

port: int = 587

Pass 465 with security="tls", because 587 is the STARTTLS port.

security: Literal["starttls", "tls", "none"] = "starttls"

"starttls" upgrades after EHLO and raises TransportError when the server does not offer it. "tls" starts TLS on connect. "none" sends in plaintext, a password included. There is no opportunistic mode, and nothing infers the mode from the port.

credential: Password | OAuth | None = None

None submits anonymously. A Password authenticates through PLAIN, LOGIN or CRAM-MD5, and an OAuth authenticates with an access token through XOAUTH2.

Raises

TypeError

When credential is none of Password, OAuth and None.

ImportError

When an OAuth holds a Graph or Gmail value, and that backend’s extra is not installed.

ValueError

When security is not one of the three modes.