295 lines
11 KiB
TeX
295 lines
11 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} (\citetitle{Simple Mail Transfer Protocol}) and \rfc{1869}
|
|
(\citetitle{SMTP Service Extensions}).
|
|
|
|
\begin{classdesc}{SMTP}{\optional{host\optional{, port\optional{,
|
|
local_hostname}}}}
|
|
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}
|
|
\seerfc{821}{Simple Mail Transfer Protocol}{Protocol definition for
|
|
SMTP. This document covers the model, operating procedure,
|
|
and protocol details for SMTP.}
|
|
\seerfc{1869}{SMTP Service Extensions}{Definition of the ESMTP
|
|
extensions for SMTP. This describes a framework for
|
|
extending SMTP with new commands, supporting dynamic
|
|
discovery of the commands provided by the server, and
|
|
defines a few additional commands.}
|
|
\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.
|
|
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_extn()}.
|
|
|
|
Unless you wish to use \method{has_extn()} 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}{login}{user, password}
|
|
Log in on an SMTP server that requires authentication.
|
|
The arguments are the username and the password to authenticate with.
|
|
If there has been no previous \samp{EHLO} or \samp{HELO} command this
|
|
session, this method tries ESMTP \samp{EHLO} first.
|
|
This method will return normally if the authentication was successful,
|
|
or may raise the following exceptions:
|
|
|
|
\begin{description}
|
|
\item[\exception{SMTPHeloError}]
|
|
The server didn't reply properly to the \samp{HELO} greeting.
|
|
\item[\exception{SMTPAuthenticationError}]
|
|
The server didn't accept the username/password combination.
|
|
\item[\exception{SMTPError}]
|
|
No suitable authentication method was found.
|
|
\end{description}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{starttls}{\optional{keyfile\optional{, certfile}}}
|
|
Put the SMTP connection in TLS (Transport Layer Security) mode. All
|
|
SMTP commands that follow will be encrypted. You should then call
|
|
\method{ehlo()} again.
|
|
|
|
If \var{keyfile} and \var{certfile} are provided, these are passed to
|
|
the \refmodule{socket} module's \function{ssl()} function.
|
|
\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.)
|
|
|
|
\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 raw_input(prompt).strip()
|
|
|
|
fromaddr = prompt("From: ")
|
|
toaddrs = prompt("To: ").split()
|
|
print "Enter message, end with ^D (Unix) or ^Z (Windows):"
|
|
|
|
# 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:
|
|
try:
|
|
line = raw_input()
|
|
except EOFError:
|
|
break
|
|
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}
|