19.2. Email Protocols

Most email today is sent via servers that implement the Simple Mail Transport Protocol (SMTP) and received via servers that implement the Post Office Protocol version 3 (POP3). These protocols are supported by the Python standard library modules smtplib and poplib. Some servers, instead of or in addition to POP3, implement the richer and more advanced Internet Message Access Protocol version 4 (IMAP4), supported by the Python standard library module imaplib, which I do not cover in this book.

19.2.1. The poplib Module

The poplib module supplies a class POP3 to access a POP mailbox. The specifications of the POP protocol are at http://www.ietf.org/rfc/rfc1939.txt.

POP3	class POP3(host,port=110) Returns an instance p of class POP3 connected to the given host and port. Instance p supplies many methods, of which the most frequently used are the following.
dele	p.dele(msgnum) Marks message msgnum for deletion. The server will perform deletions when this connection terminates by calling p.quit. dele returns the server response string.
list	p.list(msgnum=None) Returns a pair (response,messages), where response is the server response string and messages is a list of strings, each of two words 'msgnum bytes', giving the message number and the length in bytes of each message in the mailbox. When msgnum is not None, messages has only one item: a 'msgnum bytes' for the given msgnum.
pass_	p.pass_(password) Sends the password. Must be called after p.user. The trailing underscore in the name is needed because pass is a Python keyword. Returns the server response string.
quit	p.quit( ) Ends the session and tells the server to perform the deletions that were requested by calls to p.dele. Returns the server response string.
retr	p.retr(msgnum) Returns a three-item tuple (response,lines,bytes), where response is the server response string, lines is the list of all lines in message msgnum, and bytes is the total number of bytes in the message.
set_debuglevel	p.set_debuglevel(debug_level) Sets the debug level to integer debug_level: 0, the default, for no debugging; 1 to get a modest amount of debugging output; and 2 or more to get a complete output trace of all control information exchanged with the server.
stat	p.stat( ) Returns a pair (num_messages,bytes), where num_messages is the number of messages in the mailbox and bytes is the total number of bytes.
top	p.top(msgnum,maxlines) Like retr, but returns no more than maxlines lines of text from the message after the headers. Can be useful to view the start of long messages.
user	p.user(username) Sends the username. Must be followed by a call to p.pass_.

19.2.2. The smtplib Module

The smtplib module supplies a class SMTP to send mail to any SMTP server. The specifications of the SMTP protocol are at http://www.ietf.org/rfc/rfc2821.txt.

SMTP	class SMTP([host,port=25]) Returns an instance s of class SMTP. When host (and optionally port) is given, implicitly calls s.connect(host,port). Instance s supplies many methods, of which the most frequently used are the following.
connect	s.connect(host=127.0.0.1,port=25) Connects to an SMTP server on the given host (by default, the local host) and port (port 25 is the default port for the SMTP service).
login	s.login(user,password) Logs in to the server with the given user and password. Needed only if the SMTP server requires authentication.
quit	s.quit( ) Terminates the SMTP session.
sendmail	s.sendmail(from_addr,to_addrs,msg_string) Sends mail message msg_string from the sender whose address is in string from_addr to each of the recipients whose addresses are the items of list to_addrs. msg_string must be a complete RFC 822 message in a single multiline string: the headers, an empty line for separation, then the body. from_addr and to_addrs only direct the mail transport, and do not add or change headers in msg_string. To prepare RFC 822-compliant messages, use package email, covered in "MIME and Email Format Handling" on page 564.