331 lines
13 KiB
TeX
331 lines
13 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\optional{, timeout}}}}}
|
|
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.
|
|
The optional \var{timeout} parameter specifies a timeout in seconds for the
|
|
connection attempt (if not specified, or passed as None, the global
|
|
default timeout setting will be used).
|
|
|
|
For normal use, you should only require the initialization/connect,
|
|
\method{sendmail()}, and \method{quit()} methods. An example is
|
|
included below.
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{SMTP_SSL}{\optional{host\optional{, port\optional{,
|
|
local_hostname\optional{,
|
|
keyfile\optional{,
|
|
certfile\optional{, timeout}}}}}}}
|
|
A \class{SMTP_SSL} instance behaves exactly the same as instances of \class{SMTP}.
|
|
\class{SMTP_SSL} should be used for situations where SSL is required from
|
|
the beginning of the connection and using \method{starttls()} is not appropriate.
|
|
If \var{host} is not specified, the local host is used. If \var{port} is
|
|
omitted, the standard SMTP-over-SSL port (465) is used. \var{keyfile} and \var{certfile}
|
|
are also optional, and can contain a PEM formatted private key and
|
|
certificate chain file for the SSL connection.
|
|
The optional \var{timeout} parameter specifies a timeout in seconds for the
|
|
connection attempt (if not specified, or passed as None, the global
|
|
default timeout setting will be used).
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{LMTP}{\optional{host\optional{, port\optional{,
|
|
local_hostname}}}}
|
|
|
|
The LMTP protocol, which is very similar to ESMTP, is heavily based
|
|
on the standard SMTP client. It's common to use Unix sockets for LMTP,
|
|
so our connect() method must support that as well as a regular
|
|
host:port server. To specify a Unix socket, you must use an absolute
|
|
path for \var{host}, starting with a '/'.
|
|
|
|
Authentication is supported, using the regular SMTP mechanism. When
|
|
using a Unix socket, LMTP generally don't support or require any
|
|
authentication, but your mileage might vary.
|
|
|
|
\versionadded{2.6}
|
|
|
|
\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}[SMTP]{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}[SMTP]{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}[SMTP]{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}[SMTP]{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}[SMTP]{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}[SMTP]{has_extn}{name}
|
|
Return \constant{True} if \var{name} is in the set of SMTP service
|
|
extensions returned by the server, \constant{False} otherwise.
|
|
Case is ignored.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[SMTP]{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}[SMTP]{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{SMTPException}]
|
|
No suitable authentication method was found.
|
|
\end{description}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[SMTP]{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}[SMTP]{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 (a bare string will be
|
|
treated as a list with 1 address), 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}[SMTP]{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
|
|
|
|
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, ", ".join(toaddrs)))
|
|
while 1:
|
|
try:
|
|
line = raw_input()
|
|
except EOFError:
|
|
break
|
|
if not line:
|
|
break
|
|
msg = msg + line
|
|
|
|
print "Message length is " + repr(len(msg))
|
|
|
|
server = smtplib.SMTP('localhost')
|
|
server.set_debuglevel(1)
|
|
server.sendmail(fromaddr, toaddrs, msg)
|
|
server.quit()
|
|
\end{verbatim}
|