| \section{\module{smtplib} --- |
| SMTP protocol client} |
| |
| \declaremodule{standard}{smtplib} |
| \modulesynopsis{SMTP protocol client (requires sockets).} |
| \sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} |
| |
| \indexii{SMTP}{protocol} |
| \index{Simple Mail Transfer Protocol} |
| |
| The \module{smtplib} module defines an SMTP client session object that |
| can be used to send mail to any Internet machine with an SMTP or ESMTP |
| listener daemon. For details of SMTP and ESMTP operation, consult |
| \rfc{821} (\citetitle{Simple Mail Transfer Protocol}) and \rfc{1869} |
| (\citetitle{SMTP Service Extensions}). |
| |
| \begin{classdesc}{SMTP}{\optional{host\optional{, port}}} |
| A \class{SMTP} instance encapsulates an SMTP connection. It has |
| methods that support a full repertoire of SMTP and ESMTP |
| operations. If the optional host and port parameters are given, the |
| SMTP \method{connect()} method is called with those parameters during |
| initialization. An \exception{SMTPConnectError} is raised if the |
| specified host doesn't respond correctly. |
| |
| For normal use, you should only require the initialization/connect, |
| \method{sendmail()}, and \method{quit()} methods. An example is |
| included below. |
| \end{classdesc} |
| |
| |
| A nice selection of exceptions is defined as well: |
| |
| \begin{excdesc}{SMTPException} |
| Base exception class for all exceptions raised by this module. |
| \end{excdesc} |
| |
| \begin{excdesc}{SMTPServerDisconnected} |
| This exception is raised when the server unexpectedly disconnects, |
| or when an attempt is made to use the \class{SMTP} instance before |
| connecting it to a server. |
| \end{excdesc} |
| |
| \begin{excdesc}{SMTPResponseException} |
| Base class for all exceptions that include an SMTP error code. |
| These exceptions are generated in some instances when the SMTP |
| server returns an error code. The error code is stored in the |
| \member{smtp_code} attribute of the error, and the |
| \member{smtp_error} attribute is set to the error message. |
| \end{excdesc} |
| |
| \begin{excdesc}{SMTPSenderRefused} |
| Sender address refused. In addition to the attributes set by on all |
| \exception{SMTPResponseException} exceptions, this sets `sender' to |
| the string that the SMTP server refused. |
| \end{excdesc} |
| |
| \begin{excdesc}{SMTPRecipientsRefused} |
| All recipient addresses refused. The errors for each recipient are |
| accessible through the attribute \member{recipients}, which is a |
| dictionary of exactly the same sort as \method{SMTP.sendmail()} |
| returns. |
| \end{excdesc} |
| |
| \begin{excdesc}{SMTPDataError} |
| The SMTP server refused to accept the message data. |
| \end{excdesc} |
| |
| \begin{excdesc}{SMTPConnectError} |
| Error occurred during establishment of a connection with the server. |
| \end{excdesc} |
| |
| \begin{excdesc}{SMTPHeloError} |
| The server refused our \samp{HELO} message. |
| \end{excdesc} |
| |
| |
| \begin{seealso} |
| \seetext{Internet \rfc{821}, \emph{Simple Mail Transfer Protocol}. |
| Available online at |
| \url{http://info.internet.isi.edu/in-notes/rfc/files/rfc821.txt}.} |
| |
| \seetext{Internet \rfc{1869}, \emph{SMTP Service Extensions}. |
| Available online at |
| \url{http://info.internet.isi.edu/in-notes/rfc/files/rfc1869.txt}.} |
| \end{seealso} |
| |
| |
| \subsection{SMTP Objects \label{SMTP-objects}} |
| |
| An \class{SMTP} instance has the following methods: |
| |
| \begin{methoddesc}{set_debuglevel}{level} |
| Set the debug output level. A true value for \var{level} results in |
| debug messages for connection and for all messages sent to and |
| received from the server. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{connect}{\optional{host\optional{, port}}} |
| Connect to a host on a given port. The defaults are to connect to the |
| local host at the standard SMTP port (25). |
| |
| If the hostname ends with a colon (\character{:}) followed by a |
| number, that suffix will be stripped off and the number interpreted as |
| the port number to use. |
| |
| Note: This method is automatically invoked by the constructor if a |
| host is specified during instantiation. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{docmd}{cmd, \optional{, argstring}} |
| Send a command \var{cmd} to the server. The optional argument |
| \var{argstring} is simply concatenated to the command, separated by a |
| space. |
| |
| This returns a 2-tuple composed of a numeric response code and the |
| actual response line (multiline responses are joined into one long |
| line.) |
| |
| In normal operation it should not be necessary to call this method |
| explicitly. It is used to implement other methods and may be useful |
| for testing private extensions. |
| |
| If the connection to the server is lost while waiting for the reply, |
| \exception{SMTPServerDisconnected} will be raised. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{helo}{\optional{hostname}} |
| Identify yourself to the SMTP server using \samp{HELO}. The hostname |
| argument defaults to the fully qualified domain name of the local |
| host. |
| |
| In normal operation it should not be necessary to call this method |
| explicitly. It will be implicitly called by the \method{sendmail()} |
| when necessary. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{ehlo}{\optional{hostname}} |
| Identify yourself to an ESMTP server using \samp{EHLO}. The hostname |
| argument defaults to the fully qualified domain name of the local |
| host. Examine the response for ESMTP option and store them for use by |
| \method{has_option()}. |
| |
| Unless you wish to use \method{has_option()} before sending |
| mail, it should not be necessary to call this method explicitly. It |
| will be implicitly called by \method{sendmail()} when necessary. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{has_extn}{name} |
| Return \code{1} if \var{name} is in the set of SMTP service extensions |
| returned by the server, \code{0} otherwise. Case is ignored. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{verify}{address} |
| Check the validity of an address on this server using SMTP \samp{VRFY}. |
| Returns a tuple consisting of code 250 and a full \rfc{822} address |
| (including human name) if the user address is valid. Otherwise returns |
| an SMTP error code of 400 or greater and an error string. |
| |
| Note: many sites disable SMTP \samp{VRFY} in order to foil spammers. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{, |
| mail_options, rcpt_options}} |
| Send mail. The required arguments are an \rfc{822} from-address |
| string, a list of \rfc{822} to-address strings, and a message string. |
| The caller may pass a list of ESMTP options (such as \samp{8bitmime}) |
| to be used in \samp{MAIL FROM} commands as \var{mail_options}. ESMTP |
| options (such as \samp{DSN} commands) that should be used with all |
| \samp{RCPT} commands can be passed as \var{rcpt_options}. (If you |
| need to use different ESMTP options to different recipients you have |
| to use the low-level methods such as \method{mail}, \method{rcpt} and |
| \method{data} to send the message.) |
| |
| \strong{Note:} The \var{from_addr} and \var{to_addrs} parameters are |
| used to construct the message envelope used by the transport agents. |
| The \class{SMTP} does not modify the message headers in any way. |
| |
| If there has been no previous \samp{EHLO} or \samp{HELO} command this |
| session, this method tries ESMTP \samp{EHLO} first. If the server does |
| ESMTP, message size and each of the specified options will be passed |
| to it (if the option is in the feature set the server advertises). If |
| \samp{EHLO} fails, \samp{HELO} will be tried and ESMTP options |
| suppressed. |
| |
| This method will return normally if the mail is accepted for at least |
| one recipient. Otherwise it will throw an exception. That is, if this |
| method does not throw an exception, then someone should get your mail. |
| If this method does not throw an exception, it returns a dictionary, |
| with one entry for each recipient that was refused. Each entry |
| contains a tuple of the SMTP error code and the accompanying error |
| message sent by the server. |
| |
| This method may raise the following exceptions: |
| |
| \begin{description} |
| \item[\exception{SMTPRecipientsRefused}] |
| All recipients were refused. Nobody got the mail. The |
| \member{recipients} attribute of the exception object is a dictionary |
| with information about the refused recipients (like the one returned |
| when at least one recipient was accepted). |
| |
| \item[\exception{SMTPHeloError}] |
| The server didn't reply properly to the \samp{HELO} greeting. |
| |
| \item[\exception{SMTPSenderRefused}] |
| The server didn't accept the \var{from_addr}. |
| |
| \item[\exception{SMTPDataError}] |
| The server replied with an unexpected error code (other than a refusal |
| of a recipient). |
| \end{description} |
| |
| Unless otherwise noted, the connection will be open even after |
| an exception is raised. |
| |
| \end{methoddesc} |
| |
| \begin{methoddesc}{quit}{} |
| Terminate the SMTP session and close the connection. |
| \end{methoddesc} |
| |
| Low-level methods corresponding to the standard SMTP/ESMTP commands |
| \samp{HELP}, \samp{RSET}, \samp{NOOP}, \samp{MAIL}, \samp{RCPT}, and |
| \samp{DATA} are also supported. Normally these do not need to be |
| called directly, so they are not documented here. For details, |
| consult the module code. |
| |
| |
| \subsection{SMTP Example \label{SMTP-example}} |
| |
| This example prompts the user for addresses needed in the message |
| envelope (`To' and `From' addresses), and the message to be |
| delivered. Note that the headers to be included with the message must |
| be included in the message as entered; this example doesn't do any |
| processing of the \rfc{822} headers. In particular, the `To' and |
| `From' addresses must be included in the message headers explicitly. |
| |
| \begin{verbatim} |
| import smtplib |
| import string |
| |
| def prompt(prompt): |
| return string.strip(raw_input(prompt)) |
| |
| fromaddr = prompt("From: ") |
| toaddrs = string.split(prompt("To: ")) |
| print "Enter message, end with ^D:" |
| |
| # Add the From: and To: headers at the start! |
| msg = ("From: %s\r\nTo: %s\r\n\r\n" |
| % (fromaddr, string.join(toaddrs, ", "))) |
| while 1: |
| line = raw_input() |
| if not line: |
| break |
| msg = msg + line |
| |
| print "Message length is " + `len(msg)` |
| |
| server = smtplib.SMTP('localhost') |
| server.set_debuglevel(1) |
| server.sendmail(fromaddr, toaddrs, msg) |
| server.quit() |
| \end{verbatim} |