| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="lib.html" title='Python Library Reference' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="SMTP-example.html" /> |
| 13 | <link rel="prev" href="module-smtplib.html" /> |
| 14 | <link rel="parent" href="module-smtplib.html" /> |
| 15 | <link rel="next" href="SMTP-example.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>11.12.1 SMTP Objects </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="11.12 smtplib " |
| 25 | href="module-smtplib.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="11.12 smtplib " |
| 28 | href="module-smtplib.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="11.12.2 SMTP Example" |
| 31 | href="SMTP-example.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python Library Reference</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 38 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="module-smtplib.html">11.12 smtplib </A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="module-smtplib.html">11.12 smtplib </A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="SMTP-example.html">11.12.2 SMTP Example</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H2><A NAME="SECTION00131210000000000000000"></A><A NAME="SMTP-objects"></A> |
| 56 | <BR> |
| 57 | 11.12.1 SMTP Objects |
| 58 | </H2> |
| 59 | |
| 60 | <P> |
| 61 | An <tt class="class">SMTP</tt> instance has the following methods: |
| 62 | |
| 63 | <P> |
| 64 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 65 | <td><nobr><b><tt id='l2h-3498' xml:id='l2h-3498' class="method">set_debuglevel</tt></b>(</nobr></td> |
| 66 | <td><var>level</var>)</td></tr></table></dt> |
| 67 | <dd> |
| 68 | Set the debug output level. A true value for <var>level</var> results in |
| 69 | debug messages for connection and for all messages sent to and |
| 70 | received from the server. |
| 71 | </dl> |
| 72 | |
| 73 | <P> |
| 74 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 75 | <td><nobr><b><tt id='l2h-3499' xml:id='l2h-3499' class="method">connect</tt></b>(</nobr></td> |
| 76 | <td><var></var><big>[</big><var>host</var><big>[</big><var>, port</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 77 | <dd> |
| 78 | Connect to a host on a given port. The defaults are to connect to the |
| 79 | local host at the standard SMTP port (25). |
| 80 | If the hostname ends with a colon ("<tt class="character">:</tt>") followed by a |
| 81 | number, that suffix will be stripped off and the number interpreted as |
| 82 | the port number to use. |
| 83 | This method is automatically invoked by the constructor if a |
| 84 | host is specified during instantiation. |
| 85 | </dl> |
| 86 | |
| 87 | <P> |
| 88 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 89 | <td><nobr><b><tt id='l2h-3500' xml:id='l2h-3500' class="method">docmd</tt></b>(</nobr></td> |
| 90 | <td><var>cmd, </var><big>[</big><var>, argstring</var><big>]</big><var></var>)</td></tr></table></dt> |
| 91 | <dd> |
| 92 | Send a command <var>cmd</var> to the server. The optional argument |
| 93 | <var>argstring</var> is simply concatenated to the command, separated by a |
| 94 | space. |
| 95 | |
| 96 | <P> |
| 97 | This returns a 2-tuple composed of a numeric response code and the |
| 98 | actual response line (multiline responses are joined into one long |
| 99 | line.) |
| 100 | |
| 101 | <P> |
| 102 | In normal operation it should not be necessary to call this method |
| 103 | explicitly. It is used to implement other methods and may be useful |
| 104 | for testing private extensions. |
| 105 | |
| 106 | <P> |
| 107 | If the connection to the server is lost while waiting for the reply, |
| 108 | <tt class="exception">SMTPServerDisconnected</tt> will be raised. |
| 109 | </dl> |
| 110 | |
| 111 | <P> |
| 112 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 113 | <td><nobr><b><tt id='l2h-3501' xml:id='l2h-3501' class="method">helo</tt></b>(</nobr></td> |
| 114 | <td><var></var><big>[</big><var>hostname</var><big>]</big><var></var>)</td></tr></table></dt> |
| 115 | <dd> |
| 116 | Identify yourself to the SMTP server using "<tt class="samp">HELO</tt>". The hostname |
| 117 | argument defaults to the fully qualified domain name of the local |
| 118 | host. |
| 119 | |
| 120 | <P> |
| 121 | In normal operation it should not be necessary to call this method |
| 122 | explicitly. It will be implicitly called by the <tt class="method">sendmail()</tt> |
| 123 | when necessary. |
| 124 | </dl> |
| 125 | |
| 126 | <P> |
| 127 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 128 | <td><nobr><b><tt id='l2h-3502' xml:id='l2h-3502' class="method">ehlo</tt></b>(</nobr></td> |
| 129 | <td><var></var><big>[</big><var>hostname</var><big>]</big><var></var>)</td></tr></table></dt> |
| 130 | <dd> |
| 131 | Identify yourself to an ESMTP server using "<tt class="samp">EHLO</tt>". The hostname |
| 132 | argument defaults to the fully qualified domain name of the local |
| 133 | host. Examine the response for ESMTP option and store them for use by |
| 134 | <tt class="method">has_extn()</tt>. |
| 135 | |
| 136 | <P> |
| 137 | Unless you wish to use <tt class="method">has_extn()</tt> before sending |
| 138 | mail, it should not be necessary to call this method explicitly. It |
| 139 | will be implicitly called by <tt class="method">sendmail()</tt> when necessary. |
| 140 | </dl> |
| 141 | |
| 142 | <P> |
| 143 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 144 | <td><nobr><b><tt id='l2h-3503' xml:id='l2h-3503' class="method">has_extn</tt></b>(</nobr></td> |
| 145 | <td><var>name</var>)</td></tr></table></dt> |
| 146 | <dd> |
| 147 | Return <tt class="constant">True</tt> if <var>name</var> is in the set of SMTP service |
| 148 | extensions returned by the server, <tt class="constant">False</tt> otherwise. |
| 149 | Case is ignored. |
| 150 | </dl> |
| 151 | |
| 152 | <P> |
| 153 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 154 | <td><nobr><b><tt id='l2h-3504' xml:id='l2h-3504' class="method">verify</tt></b>(</nobr></td> |
| 155 | <td><var>address</var>)</td></tr></table></dt> |
| 156 | <dd> |
| 157 | Check the validity of an address on this server using SMTP "<tt class="samp">VRFY</tt>". |
| 158 | Returns a tuple consisting of code 250 and a full <a class="rfc" id='rfcref-90338' xml:id='rfcref-90338' |
| 159 | href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a> address |
| 160 | (including human name) if the user address is valid. Otherwise returns |
| 161 | an SMTP error code of 400 or greater and an error string. |
| 162 | |
| 163 | <P> |
| 164 | <span class="note"><b class="label">Note:</b> |
| 165 | Many sites disable SMTP "<tt class="samp">VRFY</tt>" in order to foil spammers.</span> |
| 166 | </dl> |
| 167 | |
| 168 | <P> |
| 169 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 170 | <td><nobr><b><tt id='l2h-3505' xml:id='l2h-3505' class="method">login</tt></b>(</nobr></td> |
| 171 | <td><var>user, password</var>)</td></tr></table></dt> |
| 172 | <dd> |
| 173 | Log in on an SMTP server that requires authentication. |
| 174 | The arguments are the username and the password to authenticate with. |
| 175 | If there has been no previous "<tt class="samp">EHLO</tt>" or "<tt class="samp">HELO</tt>" command this |
| 176 | session, this method tries ESMTP "<tt class="samp">EHLO</tt>" first. |
| 177 | This method will return normally if the authentication was successful, |
| 178 | or may raise the following exceptions: |
| 179 | |
| 180 | <P> |
| 181 | <DL> |
| 182 | <DT><STRONG><tt class="exception">SMTPHeloError</tt></STRONG></DT> |
| 183 | <DD>The server didn't reply properly to the "<tt class="samp">HELO</tt>" greeting. |
| 184 | |
| 185 | </DD> |
| 186 | <DT><STRONG><tt class="exception">SMTPAuthenticationError</tt></STRONG></DT> |
| 187 | <DD>The server didn't accept the username/password combination. |
| 188 | |
| 189 | </DD> |
| 190 | <DT><STRONG><tt class="exception">SMTPError</tt></STRONG></DT> |
| 191 | <DD>No suitable authentication method was found. |
| 192 | </DD> |
| 193 | </DL> |
| 194 | </dl> |
| 195 | |
| 196 | <P> |
| 197 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 198 | <td><nobr><b><tt id='l2h-3506' xml:id='l2h-3506' class="method">starttls</tt></b>(</nobr></td> |
| 199 | <td><var></var><big>[</big><var>keyfile</var><big>[</big><var>, certfile</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> |
| 200 | <dd> |
| 201 | Put the SMTP connection in TLS (Transport Layer Security) mode. All |
| 202 | SMTP commands that follow will be encrypted. You should then call |
| 203 | <tt class="method">ehlo()</tt> again. |
| 204 | |
| 205 | <P> |
| 206 | If <var>keyfile</var> and <var>certfile</var> are provided, these are passed to |
| 207 | the <tt class="module"><a href="module-socket.html">socket</a></tt> module's <tt class="function">ssl()</tt> function. |
| 208 | </dl> |
| 209 | |
| 210 | <P> |
| 211 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 212 | <td><nobr><b><tt id='l2h-3507' xml:id='l2h-3507' class="method">sendmail</tt></b>(</nobr></td> |
| 213 | <td><var>from_addr, to_addrs, msg</var><big>[</big><var>, |
| 214 | mail_options, rcpt_options</var><big>]</big><var></var>)</td></tr></table></dt> |
| 215 | <dd> |
| 216 | Send mail. The required arguments are an <a class="rfc" id='rfcref-90340' xml:id='rfcref-90340' |
| 217 | href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a> from-address |
| 218 | string, a list of <a class="rfc" id='rfcref-90342' xml:id='rfcref-90342' |
| 219 | href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a> to-address strings (a bare string will be |
| 220 | treated as a list with 1 address), and a message string. The caller |
| 221 | may pass a list of ESMTP options (such as "<tt class="samp">8bitmime</tt>") to be used |
| 222 | in "<tt class="samp">MAIL FROM</tt>" commands as <var>mail_options</var>. ESMTP options |
| 223 | (such as "<tt class="samp">DSN</tt>" commands) that should be used with all "<tt class="samp">RCPT</tt>"commands can be passed as <var>rcpt_options</var>. (If you need to use |
| 224 | different ESMTP options to different recipients you have to use the |
| 225 | low-level methods such as <tt class="method">mail</tt>, <tt class="method">rcpt</tt> and |
| 226 | <tt class="method">data</tt> to send the message.) |
| 227 | |
| 228 | <P> |
| 229 | <span class="note"><b class="label">Note:</b> |
| 230 | The <var>from_addr</var> and <var>to_addrs</var> parameters are |
| 231 | used to construct the message envelope used by the transport agents. |
| 232 | The <tt class="class">SMTP</tt> does not modify the message headers in any way.</span> |
| 233 | |
| 234 | <P> |
| 235 | If there has been no previous "<tt class="samp">EHLO</tt>" or "<tt class="samp">HELO</tt>" command this |
| 236 | session, this method tries ESMTP "<tt class="samp">EHLO</tt>" first. If the server does |
| 237 | ESMTP, message size and each of the specified options will be passed |
| 238 | to it (if the option is in the feature set the server advertises). If |
| 239 | "<tt class="samp">EHLO</tt>" fails, "<tt class="samp">HELO</tt>" will be tried and ESMTP options |
| 240 | suppressed. |
| 241 | |
| 242 | <P> |
| 243 | This method will return normally if the mail is accepted for at least |
| 244 | one recipient. Otherwise it will throw an exception. That is, if this |
| 245 | method does not throw an exception, then someone should get your mail. |
| 246 | If this method does not throw an exception, it returns a dictionary, |
| 247 | with one entry for each recipient that was refused. Each entry |
| 248 | contains a tuple of the SMTP error code and the accompanying error |
| 249 | message sent by the server. |
| 250 | |
| 251 | <P> |
| 252 | This method may raise the following exceptions: |
| 253 | |
| 254 | <P> |
| 255 | <DL> |
| 256 | <DT><STRONG><tt class="exception">SMTPRecipientsRefused</tt></STRONG></DT> |
| 257 | <DD>All recipients were refused. Nobody got the mail. The |
| 258 | <tt class="member">recipients</tt> attribute of the exception object is a dictionary |
| 259 | with information about the refused recipients (like the one returned |
| 260 | when at least one recipient was accepted). |
| 261 | |
| 262 | <P> |
| 263 | </DD> |
| 264 | <DT><STRONG><tt class="exception">SMTPHeloError</tt></STRONG></DT> |
| 265 | <DD>The server didn't reply properly to the "<tt class="samp">HELO</tt>" greeting. |
| 266 | |
| 267 | <P> |
| 268 | </DD> |
| 269 | <DT><STRONG><tt class="exception">SMTPSenderRefused</tt></STRONG></DT> |
| 270 | <DD>The server didn't accept the <var>from_addr</var>. |
| 271 | |
| 272 | <P> |
| 273 | </DD> |
| 274 | <DT><STRONG><tt class="exception">SMTPDataError</tt></STRONG></DT> |
| 275 | <DD>The server replied with an unexpected error code (other than a refusal |
| 276 | of a recipient). |
| 277 | </DD> |
| 278 | </DL> |
| 279 | |
| 280 | <P> |
| 281 | Unless otherwise noted, the connection will be open even after |
| 282 | an exception is raised. |
| 283 | |
| 284 | <P> |
| 285 | </dl> |
| 286 | |
| 287 | <P> |
| 288 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> |
| 289 | <td><nobr><b><tt id='l2h-3508' xml:id='l2h-3508' class="method">quit</tt></b>(</nobr></td> |
| 290 | <td><var></var>)</td></tr></table></dt> |
| 291 | <dd> |
| 292 | Terminate the SMTP session and close the connection. |
| 293 | </dl> |
| 294 | |
| 295 | <P> |
| 296 | Low-level methods corresponding to the standard SMTP/ESMTP commands |
| 297 | "<tt class="samp">HELP</tt>", "<tt class="samp">RSET</tt>", "<tt class="samp">NOOP</tt>", "<tt class="samp">MAIL</tt>", "<tt class="samp">RCPT</tt>", and |
| 298 | "<tt class="samp">DATA</tt>" are also supported. Normally these do not need to be |
| 299 | called directly, so they are not documented here. For details, |
| 300 | consult the module code. |
| 301 | |
| 302 | <P> |
| 303 | |
| 304 | <DIV CLASS="navigation"> |
| 305 | <div class='online-navigation'> |
| 306 | <p></p><hr /> |
| 307 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 308 | <tr> |
| 309 | <td class='online-navigation'><a rel="prev" title="11.12 smtplib " |
| 310 | href="module-smtplib.html"><img src='../icons/previous.png' |
| 311 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 312 | <td class='online-navigation'><a rel="parent" title="11.12 smtplib " |
| 313 | href="module-smtplib.html"><img src='../icons/up.png' |
| 314 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 315 | <td class='online-navigation'><a rel="next" title="11.12.2 SMTP Example" |
| 316 | href="SMTP-example.html"><img src='../icons/next.png' |
| 317 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 318 | <td align="center" width="100%">Python Library Reference</td> |
| 319 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 320 | href="contents.html"><img src='../icons/contents.png' |
| 321 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 322 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 323 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 324 | <td class='online-navigation'><a rel="index" title="Index" |
| 325 | href="genindex.html"><img src='../icons/index.png' |
| 326 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 327 | </tr></table> |
| 328 | <div class='online-navigation'> |
| 329 | <b class="navlabel">Previous:</b> |
| 330 | <a class="sectref" rel="prev" href="module-smtplib.html">11.12 smtplib </A> |
| 331 | <b class="navlabel">Up:</b> |
| 332 | <a class="sectref" rel="parent" href="module-smtplib.html">11.12 smtplib </A> |
| 333 | <b class="navlabel">Next:</b> |
| 334 | <a class="sectref" rel="next" href="SMTP-example.html">11.12.2 SMTP Example</A> |
| 335 | </div> |
| 336 | </div> |
| 337 | <hr /> |
| 338 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 339 | </DIV> |
| 340 | <!--End of Navigation Panel--> |
| 341 | <ADDRESS> |
| 342 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 343 | </ADDRESS> |
| 344 | </BODY> |
| 345 | </HTML> |