Home
Ratchet Library :: API Reference
API  ·  Manual

Module ratchet.smtp.client

This library provides client-side access to an SMTP server, commonly used to transport email messages. Currently the client will take advantage of the SIZE, STARTTLS and PIPELINING extensions and can send custom, arbitrary commands. It is provided for convenience and as an example of using the ratchet libraries.

Functions

custom_command (self, command, arg) Sends a custom command.
data (self) Sends the DATA command, indicating to the server that you are ready to send message data.
ehlo (self, ehlo_as) Sends the EHLO command.
get_banner (self) Receives the SMTP banner from the server.
helo (self, helo_as) Sends the HELO command.
mailfrom (self, address, data_size) Sends a MAIL FROM command, which starts a new message transmission on the session and specifies the sending address.
new (socket, iter_size) Creates a new SMTP client object.
quit (self) Sends a QUIT command, and closes the connection.
rcptto (self, address) Sends a RCPT TO command, which specifies one (of possibly many) recipient for the current message transaction, as started by mailfrom().
rset (self) Sends a RSET command.
send_data (self, data) Sends arbitrary message data.
send_empty_data (self) Sends empty message data.
starttls (self) Sends a STARTTLS request to the server, which indicates that, on a 250 reply from the server, you will initiate a TLS handshake.


Functions

custom_command (self, command, arg)
Sends a custom command. This function implies no logic, but does expect a standard SMTP code-message reply from the server. It is safe to expect the reply table to be populated when this function returns.

Parameters

  • self: the smtp.client object.
  • command: The SMTP command to send.
  • arg: A string to send as an argument to the command, if applicable.

Return value:

A reply table with "code" and "message" keys.
data (self)
Sends the DATA command, indicating to the server that you are ready to send message data. When this function returns, its reply table as well as those returned by mailfrom() and rcptto() will be populated. If the reply code is a 354, the SMTP protocol requires you send message data, ending with a ".", even if the mailfrom() or rcptto() commands failed.

Parameters

  • self: the smtp.client object.

Return value:

A reply table with "code" and "message" keys.
ehlo (self, ehlo_as)
Sends the EHLO command. When this function returns, you can safely expect the return table to be populated. The "message" string in the reply table does not include lines designated as SMTP extensions, these are parsed out into the "extensions" member object, see manual for details.

Parameters

  • self: the smtp.client object.
  • ehlo_as: The string to identify as.

Return value:

A reply table with "code" and "message" keys.
get_banner (self)
Receives the SMTP banner from the server. When this function returns, you can safely expect the return table to be populated.

Parameters

  • self: the smtp.client object.

Return value:

A reply table with "code" and "message" keys.
helo (self, helo_as)
Sends the HELO command. When this function returns, you can safely expect the return table to be populated.

Parameters

  • self: the smtp.client object.
  • helo_as: The string to identify as.

Return value:

A reply table with "code" and "message" keys.
mailfrom (self, address, data_size)
Sends a MAIL FROM command, which starts a new message transmission on the session and specifies the sending address. This function will also add the "SIZE=nnn" parameter, if the SIZE extension is supported by the server, where "nnn" is the data_size parameter. When this function returns, the reply table WILL NOT be populated if the server supports the PIPELINING extension. You can only safely expect the return table to be populated after calling the data() function.

Parameters

  • self: the smtp.client object.
  • address: The sender address of the message envelope.
  • data_size: The approximate size of the message data.

Return value:

A reply table with "code" and "message" keys.
new (socket, iter_size)
Creates a new SMTP client object.

Parameters

  • socket: Used as the underlying socket for the session, under the assumption that no I/O has taken place, except possibly encryption if not using STARTTLS.
  • iter_size: Maximum size of each iteration over message data, defaults to 1024 bytes at a time.

Return value:

a new smtp.client object.
quit (self)
Sends a QUIT command, and closes the connection. You can safely expect the return table to be populated, when this function returns.

Parameters

  • self: the smtp.client object.

Return value:

A reply table with "code" and "message" keys.
rcptto (self, address)
Sends a RCPT TO command, which specifies one (of possibly many) recipient for the current message transaction, as started by mailfrom(). When this function returns the reply table WILL NOT be populated if the server supports the PIPELINING extension. You can only safely expect the return table to be populated after calling the data() function.

Parameters

  • self: the smtp.client object.
  • address: A recipient address to add to the envelope.

Return value:

A reply table with "code" and "message" keys.
rset (self)
Sends a RSET command. When this function returns, you can safely expect the return table to be populated.

Parameters

  • self: the smtp.client object.

Return value:

A reply table with "code" and "message" keys.
send_data (self, data)
Sends arbitrary message data. This function will apply the transparency filters specified by the RFC, so no special care must be taken with the message data before sending it. When message data has been sent, the end marker "." is also sent. It is not safe to expect the reply table to be populated when this function returns, if the server supports the PIPELINING extension.

Parameters

  • self: the smtp.client object.
  • data: The message data, typically as per RFC 2822.

Return value:

A reply table with "code" and "message" keys.
send_empty_data (self)
Sends empty message data. This function simply sends the message end marker, ".", and should be used when the server replied to the data() function with a "354" code but calls to mailfrom() or rcptto() were not successful. It is not safe to expect the reply table to be populated when this function returns, if the server supports the PIPELINING extension.

Parameters

  • self: the smtp.client object.

Return value:

A reply table with "code" and "message" keys.
starttls (self)
Sends a STARTTLS request to the server, which indicates that, on a 250 reply from the server, you will initiate a TLS handshake. This function does not do the TLS handshake. When this function returns, you can safely expect the return table to be populated.

Parameters

  • self: the smtp.client object.

Return value:

A reply table with "code" and "message" keys.