Doc/lib/libsmtplib.tex

   1 \section{\module{smtplib} ---
   2          SMTP protocol client}
   3
   4 \declaremodule{standard}{smtplib}
   5 \modulesynopsis{SMTP protocol client (requires sockets).}
   6 \sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
   7
   8 \indexii{SMTP}{protocol}
   9 \index{Simple Mail Transfer Protocol}
  10
  11 The \module{smtplib} module defines an SMTP client session object that
  12 can be used to send mail to any Internet machine with an SMTP or ESMTP
  13 listener daemon.  For details of SMTP and ESMTP operation, consult
  14 \rfc{821} (\citetitle{Simple Mail Transfer Protocol}) and \rfc{1869}
  15 (\citetitle{SMTP Service Extensions}).
  16
  17 \begin{classdesc}{SMTP}{\optional{host\optional{, port}}}
  18 A \class{SMTP} instance encapsulates an SMTP connection.  It has
  19 methods that support a full repertoire of SMTP and ESMTP
  20 operations. If the optional host and port parameters are given, the
  21 SMTP \method{connect()} method is called with those parameters during
  22 initialization.  An \exception{SMTPConnectError} is raised if the
  23 specified host doesn't respond correctly.
  24
  25 For normal use, you should only require the initialization/connect,
  26 \method{sendmail()}, and \method{quit()} methods.  An example is
  27 included below.
  28 \end{classdesc}
  29
  30
  31 A nice selection of exceptions is defined as well:
  32
  33 \begin{excdesc}{SMTPException}
  34   Base exception class for all exceptions raised by this module.
  35 \end{excdesc}
  36
  37 \begin{excdesc}{SMTPServerDisconnected}
  38   This exception is raised when the server unexpectedly disconnects,
  39   or when an attempt is made to use the \class{SMTP} instance before
  40   connecting it to a server.
  41 \end{excdesc}
  42
  43 \begin{excdesc}{SMTPResponseException}
  44   Base class for all exceptions that include an SMTP error code.
  45   These exceptions are generated in some instances when the SMTP
  46   server returns an error code.  The error code is stored in the
  47   \member{smtp_code} attribute of the error, and the
  48   \member{smtp_error} attribute is set to the error message.
  49 \end{excdesc}
  50
  51 \begin{excdesc}{SMTPSenderRefused}
  52   Sender address refused.  In addition to the attributes set by on all
  53   \exception{SMTPResponseException} exceptions, this sets `sender' to
  54   the string that the SMTP server refused.
  55 \end{excdesc}
  56
  57 \begin{excdesc}{SMTPRecipientsRefused}
  58   All recipient addresses refused.  The errors for each recipient are
  59   accessible through the attribute \member{recipients}, which is a
  60   dictionary of exactly the same sort as \method{SMTP.sendmail()}
  61   returns.
  62 \end{excdesc}
  63
  64 \begin{excdesc}{SMTPDataError}
  65   The SMTP server refused to accept the message data.
  66 \end{excdesc}
  67
  68 \begin{excdesc}{SMTPConnectError}
  69   Error occurred during establishment of a connection  with the server.
  70 \end{excdesc}
  71
  72 \begin{excdesc}{SMTPHeloError}
  73   The server refused our \samp{HELO} message.
  74 \end{excdesc}
  75
  76
  77 \begin{seealso}
  78   \seerfc{821}{Simple Mail Transfer Protocol}{Protocol definition for
  79           SMTP.  This document covers the model, operating procedure,
  80           and protocol details for SMTP.}
  81   \seerfc{1869}{SMTP Service Extensions}{Definition of the ESMTP
  82           extensions for SMTP.  This describes a framework for
  83           extending SMTP with new commands, supporting dynamic
  84           discovery of the commands provided by the server, and
  85           defines a few additional commands.}
  86 \end{seealso}
  87
  88
  89 \subsection{SMTP Objects \label{SMTP-objects}}
  90
  91 An \class{SMTP} instance has the following methods:
  92
  93 \begin{methoddesc}{set_debuglevel}{level}
  94 Set the debug output level.  A true value for \var{level} results in
  95 debug messages for connection and for all messages sent to and
  96 received from the server.
  97 \end{methoddesc}
  98
  99 \begin{methoddesc}{connect}{\optional{host\optional{, port}}}
 100 Connect to a host on a given port.  The defaults are to connect to the
 101 local host at the standard SMTP port (25).
 102
 103 If the hostname ends with a colon (\character{:}) followed by a
 104 number, that suffix will be stripped off and the number interpreted as
 105 the port number to use.
 106
 107 Note:  This method is automatically invoked by the constructor if a
 108 host is specified during instantiation.
 109 \end{methoddesc}
 110
 111 \begin{methoddesc}{docmd}{cmd, \optional{, argstring}}
 112 Send a command \var{cmd} to the server.  The optional argument
 113 \var{argstring} is simply concatenated to the command, separated by a
 114 space.
 115
 116 This returns a 2-tuple composed of a numeric response code and the
 117 actual response line (multiline responses are joined into one long
 118 line.)
 119
 120 In normal operation it should not be necessary to call this method
 121 explicitly.  It is used to implement other methods and may be useful
 122 for testing private extensions.
 123
 124 If the connection to the server is lost while waiting for the reply,
 125 \exception{SMTPServerDisconnected} will be raised.
 126 \end{methoddesc}
 127
 128 \begin{methoddesc}{helo}{\optional{hostname}}
 129 Identify yourself to the SMTP server using \samp{HELO}.  The hostname
 130 argument defaults to the fully qualified domain name of the local
 131 host.
 132
 133 In normal operation it should not be necessary to call this method
 134 explicitly.  It will be implicitly called by the \method{sendmail()}
 135 when necessary.
 136 \end{methoddesc}
 137
 138 \begin{methoddesc}{ehlo}{\optional{hostname}}
 139 Identify yourself to an ESMTP server using \samp{EHLO}.  The hostname
 140 argument defaults to the fully qualified domain name of the local
 141 host.  Examine the response for ESMTP option and store them for use by
 142 \method{has_option()}.
 143
 144 Unless you wish to use \method{has_option()} before sending
 145 mail, it should not be necessary to call this method explicitly.  It
 146 will be implicitly called by \method{sendmail()} when necessary.
 147 \end{methoddesc}
 148
 149 \begin{methoddesc}{has_extn}{name}
 150 Return \code{1} if \var{name} is in the set of SMTP service extensions
 151 returned by the server, \code{0} otherwise.  Case is ignored.
 152 \end{methoddesc}
 153
 154 \begin{methoddesc}{verify}{address}
 155 Check the validity of an address on this server using SMTP \samp{VRFY}.
 156 Returns a tuple consisting of code 250 and a full \rfc{822} address
 157 (including human name) if the user address is valid. Otherwise returns
 158 an SMTP error code of 400 or greater and an error string.
 159
 160 Note: many sites disable SMTP \samp{VRFY} in order to foil spammers.
 161 \end{methoddesc}
 162
 163 \begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{,
 164                              mail_options, rcpt_options}}
 165 Send mail.  The required arguments are an \rfc{822} from-address
 166 string, a list of \rfc{822} to-address strings, and a message string.
 167 The caller may pass a list of ESMTP options (such as \samp{8bitmime})
 168 to be used in \samp{MAIL FROM} commands as \var{mail_options}.  ESMTP
 169 options (such as \samp{DSN} commands) that should be used with all
 170 \samp{RCPT} commands can be passed as \var{rcpt_options}.  (If you
 171 need to use different ESMTP options to different recipients you have
 172 to use the low-level methods such as \method{mail}, \method{rcpt} and
 173 \method{data} to send the message.)
 174
 175 \strong{Note:}  The \var{from_addr} and \var{to_addrs} parameters are
 176 used to construct the message envelope used by the transport agents.
 177 The \class{SMTP} does not modify the message headers in any way.
 178
 179 If there has been no previous \samp{EHLO} or \samp{HELO} command this
 180 session, this method tries ESMTP \samp{EHLO} first. If the server does
 181 ESMTP, message size and each of the specified options will be passed
 182 to it (if the option is in the feature set the server advertises).  If
 183 \samp{EHLO} fails, \samp{HELO} will be tried and ESMTP options
 184 suppressed.
 185
 186 This method will return normally if the mail is accepted for at least
 187 one recipient. Otherwise it will throw an exception.  That is, if this
 188 method does not throw an exception, then someone should get your mail.
 189 If this method does not throw an exception, it returns a dictionary,
 190 with one entry for each recipient that was refused.  Each entry
 191 contains a tuple of the SMTP error code and the accompanying error
 192 message sent by the server.
 193
 194 This method may raise the following exceptions:
 195
 196 \begin{description}
 197 \item[\exception{SMTPRecipientsRefused}]
 198 All recipients were refused.  Nobody got the mail.  The
 199 \member{recipients} attribute of the exception object is a dictionary
 200 with information about the refused recipients (like the one returned
 201 when at least one recipient was accepted).
 202
 203 \item[\exception{SMTPHeloError}]
 204 The server didn't reply properly to the \samp{HELO} greeting.
 205
 206 \item[\exception{SMTPSenderRefused}]
 207 The server didn't accept the \var{from_addr}.
 208
 209 \item[\exception{SMTPDataError}]
 210 The server replied with an unexpected error code (other than a refusal
 211 of a recipient).
 212 \end{description}
 213
 214 Unless otherwise noted, the connection will be open even after
 215 an exception is raised.
 216
 217 \end{methoddesc}
 218
 219 \begin{methoddesc}{quit}{}
 220 Terminate the SMTP session and close the connection.
 221 \end{methoddesc}
 222
 223 Low-level methods corresponding to the standard SMTP/ESMTP commands
 224 \samp{HELP}, \samp{RSET}, \samp{NOOP}, \samp{MAIL}, \samp{RCPT}, and
 225 \samp{DATA} are also supported.  Normally these do not need to be
 226 called directly, so they are not documented here.  For details,
 227 consult the module code.
 228
 229
 230 \subsection{SMTP Example \label{SMTP-example}}
 231
 232 This example prompts the user for addresses needed in the message
 233 envelope (`To' and `From' addresses), and the message to be
 234 delivered.  Note that the headers to be included with the message must
 235 be included in the message as entered; this example doesn't do any
 236 processing of the \rfc{822} headers.  In particular, the `To' and
 237 `From' addresses must be included in the message headers explicitly.
 238
 239 \begin{verbatim}
 240 import smtplib
 241 import string
 242
 243 def prompt(prompt):
 244     return raw_input(prompt).strip()
 245
 246 fromaddr = prompt("From: ")
 247 toaddrs  = prompt("To: ").split()
 248 print "Enter message, end with ^D:"
 249
 250 # Add the From: and To: headers at the start!
 251 msg = ("From: %s\r\nTo: %s\r\n\r\n"
 252        % (fromaddr, string.join(toaddrs, ", ")))
 253 while 1:
 254     try:
 255         line = raw_input()
 256     except EOFError:
 257         break
 258     if not line:
 259         break
 260     msg = msg + line
 261
 262 print "Message length is " + `len(msg)`
 263
 264 server = smtplib.SMTP('localhost')
 265 server.set_debuglevel(1)
 266 server.sendmail(fromaddr, toaddrs, msg)
 267 server.quit()
 268 \end{verbatim}