API Reference

Protocol

class smtpproto.protocol.ClientState(value)

Bases: Enum

Enumerates all possible protocol states.

greeting_expected = 1: expecting a greeting from the server

greeting_received = 2: received a greeting from the server, ready to authenticate

authenticating = 3: authentication in progress

authenticated = 4: authentication done

ready = 5: ready to send commands

mailtx = 6: in a mail transaction

recipient_sent = 7: sent at least one recipient

send_data = 8: ready to send the message data

data_sent = 9: message data sent

finished = 10: session finished

exception smtpproto.protocol.SMTPException

Bases: Exception

Base class for SMTP exceptions.

exception smtpproto.protocol.SMTPMissingExtension

Bases: SMTPException

Raised when a required SMTP extension is not present on the server.

exception smtpproto.protocol.SMTPUnsupportedAuthMechanism

Bases: SMTPException

Raised when trying to authenticate using a mechanism not supported by the server.

exception smtpproto.protocol.SMTPProtocolViolation

Bases: SMTPException

Raised when there has been a violation of the (E)SMTP protocol by either side.

class smtpproto.protocol.SMTPResponse(code, message)

Bases: object

Represents a response from the server.

code: int: response status code (between 100 and 599)

message: str: response message

is_error()

Return True if this is an error response, False if not.

Return type:: bool

raise_as_exception()

Raise an SMTPException from this response.

Return type:: NoReturn

class smtpproto.protocol.SMTPClientProtocol

Bases: object

The (E)SMTP protocol state machine.

property state: ClientState: The current state of the protocol.

property needs_incoming_data: bool: True if the state machine requires more data, False if not.

get_outgoing_data()

Retrieve any bytes to be sent to the server.

Return type:: bytes

property max_message_size: int | None: The maximum size of the email message (in bytes) accepted by the server.

property auth_mechanisms: frozenset[str]: The set of authentication mechanisms supported on the server.

property extensions: frozenset[str]: The set of extensions advertised by the server.

authenticate(mechanism, secret=None)

Authenticate to the server using the given mechanism and an accompanying secret.

Parameters:

mechanism (str) – the authentication mechanism (e.g. PLAIN or GSSAPI)
secret (str | None) – an optional string (usually containing the credentials) that is added as an argument to the AUTH XXX command

Return type:

None

send_authentication_data(data)

Send authentication data to the server.

This method can be called when the server responds with a 334 to an AUTH command.

Parameters:: data (str) – authentication data (ASCII compatible; usually base64 encoded)
Return type:: None

send_greeting(domain)

Send the initial greeting (EHLO or HELO).

Parameters:: domain (str) – the required domain name that represents the client side
Return type:: None

noop()

Send the NOOP command (No Operation).

Return type:: None

quit()

Send the QUIT command (required to cleanly shut down the session).

Return type:: None

mail(sender, *, smtputf8=True)

Send the MAIL FROM command (starts a mail transaction).

Parameters:

sender (str | Address) – the sender’s email address
smtputf8 (bool) – send the SMTPUTF8 option, if available on the server

Return type:

None

recipient(recipient)

Send the RCPT TO command (declare an intended recipient).

Requires an active mail transaction.

Parameters:: recipient (str | Address) – the recipient’s email address
Return type:: None

start_data()

Send the DATA command (prepare for sending the email payload).

Requires an active mail transaction, and that at least one recipient has been declared.

Return type:: None

data(message)

Send the actual email payload.

Requires that the DATA command has been sent first.

Parameters:: message (EmailMessage) – the email message
Return type:: None

reset()

Send the RSET command (cancel the active mail transaction).

Return type:: None

start_tls()

Send the STARTTLS command (signal the server to initiate a TLS handshake).

Return type:: None

feed_bytes(data)

Feed received bytes from the transport into the state machine.

if this method raises SMTPProtocolViolation, the state machine is transitioned to the finished state, and the connection should be closed.

Parameters:: data (bytes) – received bytes
Return type:: SMTPResponse | None
Returns:: a response object if a complete response was received, None otherwise
Raises:: SMTPProtocolViolation – if the server sent an invalid response

Authentication

class smtpproto.auth.JSONWebToken(*args, **kwargs)

Bases: dict

Variables:

access_token (str) – the access token
expires_in (int) – seconds after which the access token expires

class smtpproto.auth.LoginAuthenticator(username, password)

Bases: SMTPAuthenticator

Authenticates against the server with a username/password combination using the LOGIN method.

Parameters:

username (str) – user name to authenticate as
password (str) – password to authenticate with

async authenticate()

Performs authentication against the SMTP server.

This method must return an async generator. Any non-empty values the generator yields are sent to the server as authentication data. The response messages from any 334 responses are sent to the generator.

property mechanism: str: The name of the authentication mechanism (e.g. PLAIN or GSSAPI).

class smtpproto.auth.OAuth2Authenticator(username, *, grace_period=600)

Bases: SMTPAuthenticator

Authenticates against the server using OAUTH2.

In order to use this authenticator, you must subclass it and implement the get_token() method.

Parameters:

username (str) – the user name to authenticate as
grace_period (float) – number of seconds prior to token expiration to get a new one

async authenticate()

Performs authentication against the SMTP server.

This method must return an async generator. Any non-empty values the generator yields are sent to the server as authentication data. The response messages from any 334 responses are sent to the generator.

clear_cached_token()

Clear the previously stored token, if any.

Return type:: None

abstract async get_token()

Obtain a new access token.

This method will be called only when there either is no cached token, or the cached token is expired or nearing expiration. You can also use clear_cached_token() to manually erase the cached token. The expires_in field in the returned dict is the number of seconds after which the token will expire.

Note

If the backing server does not provide a value for expires_in, the implementor must fill in the value by other means.

Return type:: JSONWebToken
Returns:: a dict containing the access_token and expires_in fields

property mechanism: str: The name of the authentication mechanism (e.g. PLAIN or GSSAPI).

class smtpproto.auth.PlainAuthenticator(username, password, authorization_id='')

Bases: SMTPAuthenticator

Authenticates against the server with a username/password combination using the PLAIN method.

Parameters:

username (str) – user name to authenticate as
password (str) – password to authenticate with
authorization_id (str) – optional authorization ID

async authenticate()

Performs authentication against the SMTP server.

This method must return an async generator. Any non-empty values the generator yields are sent to the server as authentication data. The response messages from any 334 responses are sent to the generator.

property mechanism: str: The name of the authentication mechanism (e.g. PLAIN or GSSAPI).

class smtpproto.auth.SMTPAuthenticator

Bases: object

Interface for providing credentials for authenticating against SMTP servers.

abstract authenticate()

Performs authentication against the SMTP server.

This method must return an async generator. Any non-empty values the generator yields are sent to the server as authentication data. The response messages from any 334 responses are sent to the generator.

abstract property mechanism: str: The name of the authentication mechanism (e.g. PLAIN or GSSAPI).

Concrete client implementation

class smtpproto.client.AsyncSMTPClient(host, port=587, connect_timeout=30, timeout=60, domain=None, ssl_context=None, authenticator=None, max_concurrent_connections=50)

Bases: object

An asynchronous SMTP client.

This runs on asyncio or any other backend supported by AnyIO.

Parameters:

host (str) – host name or IP address of the SMTP server
port (int) – port on the SMTP server to connect to
connect_timeout (float) – connection timeout (in seconds)
timeout (float) – timeout for sending requests and reading responses (in seconds)
domain (str | None) – domain name to send to the server as part of the greeting message
ssl_context (SSLContext | None) – SSL context to use for establishing TLS encrypted sessions
authenticator (SMTPAuthenticator | None) – authenticator to use for authenticating with the SMTP server
max_concurrent_connections (int) – maximum number of connections to allows to the SMTP server before blocking

connect()

Establish a session with the SMTP server.

The returned async context manager connects to the SMTP server and performs the protocol handshake. After that, it optionally establishes an encrypted session with STARTTLS, and then logs in (if an authenticator was provided).

Returns:: a context manager yielding an AsyncSMTPSession

async send_message(message, *, sender=None, recipients=None)

Open a session with the SMTP server, send an email and then close the session.

This is a convenience method for the following:

async with client.connect() as session:
    return await session.send_message(message, sender=sender, recipients=recipients)

Parameters:

message (EmailMessage) – the message to send
sender (str | Address | None) – override the sender address in the MAIL FROM command
recipients (Iterable[str] | None) – override the destination addresses in the RCPT TO commands

Return type:

SMTPResponse

Returns:

the SMTP response

class smtpproto.client.AsyncSMTPSession(host, port, connect_timeout, timeout, domain, authenticator, ssl_context)

Bases: object

Encapsulates a live connection to an SMTP server.

Variables:: protocol (SMTPClientProtocol) – the protocol state machine

async send_command(command, /, *args, **kwargs)

Send a command to the SMTP server and return the response.

Parameters:

command – a callable from SMTPClientProtocol
args – positional arguments to command
kwargs – keyword arguments to command

async send_message(message, *, sender=None, recipients=None)

Send an email message.

Parameters:

message (EmailMessage) – the message to send
sender (str | Address | None) – override the sender address in the MAIL FROM command
recipients (Iterable[str] | None) – override the destination addresses in the RCPT TO commands

Return type:

SMTPResponse

Returns:

the SMTP response

class smtpproto.client.SyncSMTPClient(host, port=587, connect_timeout=30, timeout=60, domain=None, ssl_context=None, authenticator=None, max_concurrent_connections=50, async_backend='asyncio', async_backend_options=None)

Bases: object

A synchronous (blocking) SMTP client.

Parameters:

host (str) – host name or IP address of the SMTP server
port (int) – port on the SMTP server to connect to
connect_timeout (float) – connection timeout (in seconds)
timeout (float) – timeout for sending requests and reading responses (in seconds)
domain (str | None) – domain name to send to the server as part of the greeting message
ssl_context (SSLContext | None) – SSL context to use for establishing TLS encrypted sessions
authenticator (SMTPAuthenticator | None) – authenticator to use for authenticating with the SMTP server
max_concurrent_connections (int) – maximum number of connections to allows to the SMTP server before blocking
async_backend (str) – name of the AnyIO-supported asynchronous backend
async_backend_options (dict[str, Any] | None) – dictionary of keyword arguments passed to anyio.from_thread.start_blocking_portal()

connect()

Establish a session with the SMTP server.

The returned context manager connects to the SMTP server and performs the protocol handshake. After that, it optionally establishes an encrypted session with STARTTLS, and then logs in (if an authenticator was provided).

Returns:: a context manager yielding a SyncSMTPSession

send_message(message, *, sender=None, recipients=None)

Open a session with the SMTP server, send an email and then close the session.

This is a convenience method for the following:

with client.connect() as session:
    return session.send_message(message, sender=sender, recipients=recipients)

Parameters:

message (EmailMessage) – the message to send
sender (str | Address | None) – override the sender address in the MAIL FROM command
recipients (Iterable[str] | None) – override the destination addresses in the RCPT TO commands

Return type:

SMTPResponse

Returns:

the SMTP response

class smtpproto.client.SyncSMTPSession(portal, async_session)

Bases: object

send_command(command, /, *args, **kwargs)

Send a command to the SMTP server and return the response.

Parameters:

command – a callable from SMTPClientProtocol
args – positional arguments to command
kwargs – keyword arguments to command

send_message(message, *, sender=None, recipients=None)

Send an email message.

Parameters:

message (EmailMessage) – the message to send
sender (str | Address | None) – override the sender address in the MAIL FROM command
recipients (Iterable[str] | None) – override the destination addresses in the RCPT TO commands

Return type:

SMTPResponse

Returns:

the SMTP response