mirror of https://github.com/python/cpython
260 lines
9.4 KiB
TeX
260 lines
9.4 KiB
TeX
\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} (\emph{Simple Mail Transfer Protocol}) and \rfc{1869}
|
|
(\emph{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
|
|
accessable 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}
|
|
|
|
|
|
\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.)
|
|
|
|
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{itemize}
|
|
\item[\exception{SMTPRecipientsRefused}]
|
|
All recipients were refused. Nobody got the mail. The
|
|
\var{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 helo greeting.
|
|
|
|
\item[\exception{SMTPSenderRefused}]
|
|
The server didn't accept the from_addr.
|
|
|
|
\item[\exception{SMTPDataError}]
|
|
The server replied with an unexpected
|
|
error code (other than a refusal of
|
|
a recipient).
|
|
\end{itemize}
|
|
|
|
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
|
|
envelop (`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 rfc822, string, sys
|
|
import smtplib
|
|
|
|
def prompt(prompt):
|
|
sys.stdout.write(prompt + ": ")
|
|
return string.strip(sys.stdin.readline())
|
|
|
|
fromaddr = prompt("From")
|
|
toaddrs = string.splitfields(prompt("To"), ',')
|
|
print "Enter message, end with ^D:"
|
|
msg = ""
|
|
while 1:
|
|
line = sys.stdin.readline()
|
|
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}
|
|
|
|
|
|
\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}
|