145 lines
5.2 KiB
TeX
145 lines
5.2 KiB
TeX
% Documentation by ESR
|
|
\section{Standard Module \module{smtp}}
|
|
\stmodindex{smtp}
|
|
\label{module-smtp}
|
|
|
|
The \code{smtp} module defines an SMTP 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 (Simple Mail
|
|
Transfer Protocol) and RFC1869 (SMTP Service Extensions).
|
|
|
|
\begin{classdesc}{SMTP}{\optional{host, 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 connect method is called with those parameters during
|
|
initialization.
|
|
|
|
For normal use, you should only require the initialization/connect,
|
|
\var{sendmail}, and \var{quit} methods An example is included below.
|
|
\end{classdesc}
|
|
|
|
\subsection{SMTP Objects}
|
|
\label{SMTP-objects}
|
|
|
|
A \class{SMTP} instance has the following methods:
|
|
|
|
\begin{methoddesc}{set_debuglevel}{level}
|
|
Set the debug output level. A non-false value results in debug
|
|
messages for connection and for all messages sent to and received from
|
|
the server.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{connect}{\optional{host='localhost',port=0}}
|
|
Connect to a host on a given port.
|
|
|
|
If the hostname ends with a colon (`:') 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 __init__,
|
|
if a host is specified during instantiation.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{docmd}{cmd, \optional{, argstring}}
|
|
Send a command to the server. The optional argument
|
|
string is simply concatenated to the command.
|
|
|
|
Get back 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.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{helo}{\optional{hostname}}
|
|
Identify yourself to the SMTP server using HELO. The hostname
|
|
argument defaults to the FQDN of the local host.
|
|
|
|
In normal operation it should not be necessary to call this method
|
|
explicitly. It will be implicitly called by the \var{sendmail} method
|
|
when necessary.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{ehlo}{\optional{hostname}}
|
|
Identify yourself to an ESMTP server using HELO. The hostname
|
|
argument defaults to the FQDN of the local host. Examine the
|
|
response for ESMTP option and store them for use by the
|
|
\var{has_option} method.
|
|
|
|
Unless you wish to use the \var{has_option} method before sending
|
|
mail, it should not be necessary to call this method explicitly. It
|
|
will be implicitly called by the \var{sendmail} method when necessary.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{has_option}{name}
|
|
Return 1 if name is in the set of ESMTP options returned by the
|
|
server, 0 otherwise. Case is ignored.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{verify}{address}
|
|
Check the validity of an address on this server using SMTP VRFY.
|
|
Returns a tuple consisting of code 250 and a full RFC822 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 VRFY in order to foil spammers.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{, options=[]}}
|
|
Send mail. The required arguments are an RFC822 from-address string,
|
|
a list of RFC822 to-address strings, and a message string. The caller
|
|
may pass a list of ESMTP options to be used in MAIL FROM commands.
|
|
|
|
If there has been no previous EHLO or HELO command this session, this
|
|
method tries ESMTP 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 EHLO fails, 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 (either
|
|
SMTPSenderRefused, SMTPRecipientsRefused, or SMTPDataError)
|
|
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.
|
|
\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
|
|
HELP, RSET, NOOP, MAIL, RCPT, and 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.
|
|
|
|
Example:
|
|
|
|
\begin{verbatim}
|
|
import sys, rfc822
|
|
|
|
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 = SMTP('localhost')
|
|
server.set_debuglevel(1)
|
|
server.sendmail(fromaddr, toaddrs, msg)
|
|
server.quit()
|
|
\end{verbatim}
|
|
|