Go to the latest version of this document.

# ``twisted`.`mail`.`smtp`.`ESMTPClient``

class documentation

`class ESMTPClient(SMTPClient): (source)`

Known subclasses: `twisted.mail.relay.ESMTPRelayer`, `twisted.mail.smtp.ESMTPSender`

Constructor: `ESMTPClient(secret, contextFactory, *args, **kw)`

View In Hierarchy

A client for sending emails over ESMTP.

Method | `__getattr__` | Undocumented
Method | `__init__` | Undocumented
Method | `__setattr__` | Undocumented
Method | `authenticate` | Undocumented
Method | `connectionMade` | Called when a connection has been made, and triggers sending an `EHLO` to the server.
Method | `esmtpAUTHDeclined` | Fail because the authentication was rejected.
Method | `esmtpAUTHMalformedChallenge` | Fail because the server sent a malformed authentication challenge.
Method | `esmtpAUTHRequired` | Fail because authentication is required, but the server does not support any schemes we support.
Method | `esmtpAUTHServerError` | Fail because of some other authentication error.
Method | `esmtpEHLORequired` | Fail because authentication is required, but the server does not support ESMTP, which is required for authentication.
Method | `esmtpState_challenge` | Undocumented
Method | `esmtpState_ehlo` | Send an `EHLO` to the server.
Method | `esmtpState_serverConfig` | Handle a positive response to the EHLO command by parsing the capabilities in the server's response and then taking the most appropriate next step towards entering a mail transaction.
Method | `esmtpState_starttls` | Handle a positive response to the STARTTLS command by starting a new TLS session on `self.transport`.
Method | `esmtpTLSFailed` | Fail because the TLS handshake wasn't able to be completed.
Method | `esmtpTLSRequired` | Fail because TLS is required and the server does not support it.
Method | `registerAuthenticator` | Registers an Authenticator with the ESMTPClient. The ESMTPClient will attempt to login to the SMTP Server in the order the Authenticators are registered. The most secure Authentication mechanism should be registered first.
Method | `smtpState_maybeAuthenticated` | Called to handle the next message from the server after sending a response to a SASL challenge. The server response might be another challenge or it might indicate authentication has succeeded.
Method | `tryTLS` | Take a necessary step towards being able to begin a mail transaction.
Instance Variable | `authenticators` | Undocumented
Instance Variable | `context` | The context factory to use for STARTTLS, if desired.
Instance Variable | `heloFallback` | Whether or not to fall back to plain SMTP if the `EHLO` command is not recognised by the server. If `requireAuthentication` is `True`, or `requireTransportSecurity` is `True` and the connection is not over TLS, this fallback flag will not be honored.
Instance Variable | `requireAuthentication` | If `True`, refuse to proceed if authentication cannot be performed. Overrides `heloFallback`.
Instance Variable | `requireTransportSecurity` | If `True`, refuse to proceed if the transport cannot be secured. If the transport layer is not already secured via TLS, this will override `heloFallback`.
Instance Variable | `secret` | Undocumented
Method | `_authResponse` | Undocumented
Method | `_esmtpState_plainAuth` | Undocumented
Instance Variable | `_authinfo` | Undocumented
Instance Variable | `_expected` | Undocumented
Instance Variable | `_failresponse` | Undocumented
Instance Variable | `_okresponse` | Undocumented
Instance Variable | `_tlsMode` | Whether or not the connection is over TLS.

Inherited from `SMTPClient`:

Method | `connectionLost` | We are no longer connected
Method | `finishedFileTransfer` | Undocumented
Method | `getMailData` | Return file-like object containing data of message to be sent.
Method | `getMailFrom` | Return the email address the mail is from.
Method | `getMailTo` | Return a list of emails to send to.
Method | `lineReceived` | Override this for when each line is received.
Method | `sendError` | If an error occurs before a mail message is sent sendError will be called. This base class method sends a QUIT if the error is non-fatal and disconnects the connection.
Method | `sendLine` | Sends a line to the other end of the connection.
Method | `sentMail` | Called when an attempt to send an email is completed.
Method | `smtpConnectionFailed` | Undocumented
Method | `smtpState_data` | Undocumented
Method | `smtpState_disconnect` | Undocumented
Method | `smtpState_from` | Undocumented
Method | `smtpState_helo` | Undocumented
Method | `smtpState_msgSent` | Undocumented
Method | `smtpState_to` | Undocumented
Method | `smtpState_toOrData` | Undocumented
Method | `smtpTransferFailed` | Undocumented
Method | `timeoutConnection` | Called when the connection times out.
Method | `transformChunk` | Perform the necessary local to network newline conversion and escape leading periods.
Class Variable | `debug` | Undocumented
Class Variable | `timeout` | Undocumented
Instance Variable | `code` | Undocumented
Instance Variable | `identity` | Undocumented
Instance Variable | `lastAddress` | Undocumented
Instance Variable | `log` | Undocumented
Instance Variable | `mailFile` | Undocumented
Instance Variable | `resp` | Undocumented
Instance Variable | `successAddresses` | Undocumented
Instance Variable | `toAddresses` | Undocumented
Instance Variable | `toAddressesResult` | Undocumented
Method | `_disconnectFromServer` | Undocumented
Instance Variable | `_failureReason` | Undocumented
Instance Variable | `_from` | Undocumented

Inherited from `LineReceiver` (via `SMTPClient`):

Method | `clearLineBuffer` | Clear buffered data.
Method | `dataReceived` | Protocol.dataReceived. Translates bytes into lines, and calls lineReceived (or rawDataReceived, depending on mode.)
Method | `lineLengthExceeded` | Called when the maximum line length has been reached. Override if it needs to be dealt with in some special way.
Method | `rawDataReceived` | Override this for when raw data is received.
Method | `setLineMode` | Sets the line-mode of this receiver.
Method | `setRawMode` | Sets the raw mode of this receiver. Further data received will be sent to rawDataReceived rather than lineReceived.
Constant | `MAX_LENGTH` | The maximum length of a line to allow (If a sent line is longer than this, the connection is dropped). Default is 16384.
Class Variable | `delimiter` | The line-ending delimiter to use. By default this is `b'\r\n'`.
Instance Variable | `line_mode` | Undocumented
Instance Variable | `_buffer` | Undocumented
Instance Variable | `_busyReceiving` | Undocumented

Inherited from `Protocol` (via `SMTPClient`, `LineReceiver`):

Method | `logPrefix` | Return a prefix matching the class name, to identify log messages related to this protocol instance.
Class Variable | `factory` | Undocumented

Inherited from `BaseProtocol` (via `SMTPClient`, `LineReceiver`, `Protocol`):

Method | `makeConnection` | Make a connection to a transport and a server.
Instance Variable | `connected` | Undocumented
Instance Variable | `transport` | Undocumented

Inherited from `_PauseableMixin` (via `SMTPClient`, `LineReceiver`, `Protocol`, `BaseProtocol`):

Method | `pauseProducing` | Undocumented
Method | `resumeProducing` | Undocumented
Method | `stopProducing` | Undocumented
Instance Variable | `paused` | Undocumented

Inherited from `TimeoutMixin` (via `SMTPClient`, `LineReceiver`, `Protocol`, `BaseProtocol`, `_PauseableMixin`):

Method | `callLater` | Wrapper around `reactor.callLater` for test purpose.
Method | `resetTimeout` | Reset the timeout count down.
Method | `setTimeout` | Change the timeout period
Instance Variable | `timeOut` | The number of seconds after which to timeout the connection.
Method | `__timedOut` | Undocumented
Instance Variable | `__timeoutCall` | Undocumented

def __getattr__(self, name): (source)

Undocumented

def __init__(self, secret, contextFactory=None, *args, **kw): (source)
overrides `twisted.mail.smtp.SMTPClient.__init__`
overridden in `twisted.mail.relay.ESMTPRelayer`, `twisted.mail.smtp.ESMTPSender`

Undocumented

def __setattr__(self, name, value): (source)

Undocumented

def authenticate(self, code, resp, items): (source)

Undocumented

def connectionMade(self): (source)
from `twisted.internet.interfaces.IProtocol`
overrides `twisted.mail.smtp.SMTPClient.connectionMade`

Called when a connection has been made, and triggers sending an `EHLO` to the server.

def esmtpAUTHDeclined(self, code=-1, resp=None): (source)

Fail because the authentication was rejected.

Parameters
code:`int` | The server status code from the most recently received server message.
resp:`bytes` | The server status response from the most recently received server message.

def esmtpAUTHMalformedChallenge(self, code=-1, resp=None): (source)

Fail because the server sent a malformed authentication challenge.

Parameters
code:`int` | The server status code from the most recently received server message.
resp:`bytes` | The server status response from the most recently received server message.

def esmtpAUTHRequired(self, code=-1, resp=None): (source)

Fail because authentication is required, but the server does not support any schemes we support.

Parameters
code:`int` | The server status code from the most recently received server message.
resp:`bytes` | The server status response from the most recently received server message.

def esmtpAUTHServerError(self, code=-1, resp=None): (source)

Fail because of some other authentication error.

Parameters
code:`int` | The server status code from the most recently received server message.
resp:`bytes` | The server status response from the most recently received server message.

def esmtpEHLORequired(self, code=-1, resp=None): (source)

Fail because authentication is required, but the server does not support ESMTP, which is required for authentication.

Parameters
code:`int` | The server status code from the most recently received server message.
resp:`bytes` | The server status response from the most recently received server message.

def esmtpState_challenge(self, code, resp): (source)

Undocumented

def esmtpState_ehlo(self, code, resp): (source)

Send an `EHLO` to the server.

If `heloFallback` is `True`, and there is no requirement for TLS or authentication, the client will fall back to basic SMTP.

Parameters
code:`int` | The server status code from the most recently received server message.
resp:`bytes` | The server status response from the most recently received server message.

Returns
`None`

def esmtpState_serverConfig(self, code, resp): (source)

Handle a positive response to the EHLO command by parsing the capabilities in the server's response and then taking the most appropriate next step towards entering a mail transaction.

def esmtpState_starttls(self, code, resp): (source)

Handle a positive response to the STARTTLS command by starting a new TLS session on `self.transport`.

Upon success, re-handshake with the server to discover what capabilities it has when TLS is in use.

def esmtpTLSFailed(self, code=-1, resp=None): (source)

Fail because the TLS handshake wasn't able to be completed.

Parameters
code:`int` | The server status code from the most recently received server message.
resp:`bytes` | The server status response from the most recently received server message.

def esmtpTLSRequired(self, code=-1, resp=None): (source)

Fail because TLS is required and the server does not support it.

Parameters
code:`int` | The server status code from the most recently received server message.
resp:`bytes` | The server status response from the most recently received server message.

def registerAuthenticator(self, auth): (source)

Registers an Authenticator with the ESMTPClient. The ESMTPClient will attempt to login to the SMTP Server in the order the Authenticators are registered. The most secure Authentication mechanism should be registered first.

Parameters
auth:`IClientAuthentication` implementor | The Authentication mechanism to register

Returns
`None`

def smtpState_maybeAuthenticated(self, code, resp): (source)

Called to handle the next message from the server after sending a response to a SASL challenge. The server response might be another challenge or it might indicate authentication has succeeded.

def tryTLS(self, code, resp, items): (source)

Take a necessary step towards being able to begin a mail transaction.

The step may be to ask the server to being a TLS session. If TLS is already in use or not necessary and not available then the step may be to authenticate with the server. If TLS is necessary and not available, fail the mail transmission attempt.

This is an internal helper method.

Parameters
code:`int` | The server status code from the most recently received server message.
resp:`bytes` | The server status response from the most recently received server message.
items:`dict` mapping `bytes` to `bytes` | A mapping of ESMTP extensions offered by the server. Keys are extension identifiers and values are the associated values.

Returns
`None`

authenticators: `list` = (source)

Undocumented

context: `IOpenSSLClientConnectionCreator` = (source)

The context factory to use for STARTTLS, if desired.

heloFallback: `bool` = (source)
overridden in `twisted.mail.smtp.ESMTPSender`

Whether or not to fall back to plain SMTP if the `EHLO` command is not recognised by the server. If `requireAuthentication` is `True`, or `requireTransportSecurity` is `True` and the connection is not over TLS, this fallback flag will not be honored.

requireAuthentication: `bool` = (source)
overridden in `twisted.mail.smtp.ESMTPSender`

If `True`, refuse to proceed if authentication cannot be performed. Overrides `heloFallback`.

requireTransportSecurity: `bool` = (source)
overridden in `twisted.mail.smtp.ESMTPSender`

If `True`, refuse to proceed if the transport cannot be secured. If the transport layer is not already secured via TLS, this will override `heloFallback`.

secret = (source)

Undocumented

def _authResponse(self, auth, challenge): (source)

Undocumented

def _esmtpState_plainAuth(self, code, resp): (source)

Undocumented

_authinfo = (source)

Undocumented

_expected: `list[int]` = (source)
overrides `twisted.mail.smtp.SMTPClient._expected`

Undocumented

_failresponse = (source)
overrides `twisted.mail.smtp.SMTPClient._failresponse`

Undocumented

_okresponse = (source)
overrides `twisted.mail.smtp.SMTPClient._okresponse`

Undocumented

_tlsMode: `bool` = (source)

Whether or not the connection is over TLS.