18.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, respectively. 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.

18.2.1 The poplib Module

The poplib module supplies a class POP3 to access a POP mailbox.

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.

p.dele(msgnum)

Marks message msgnum for deletion. The server performs deletions when this connection terminates by a call to method quit. Returns the response string.

p.list(msgnum=None)

Returns a pair (response,messages) where response is the 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, list messages has only one item, a string with two words: msgnum as requested, and the length bytes.

p.pass_(password)

Sends the password. Must be called after method user. The trailing underscore in the function's name is necessary because pass is a Python keyword. Returns the response string.

p.quit(  )

Ends the session and performs the deletions that were requested by calls to method dele. Returns the response string.

p.retr(msgnum)

Returns a three-item tuple (response,lines,bytes), where response is the response string, lines is a list of all lines in message msgnum, and bytes is the total number of bytes in the message.

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; 2 or more to get a complete output trace of all control information exchanged with the server.

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.

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.

p.user(username)

Sends the username. Must be followed by a call to method pass_.

18.2.2 The smtplib Module

The smtplib module supplies a class SMTP to send mail to any SMTP server.

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.

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).

s.login(user,password)

Logs in to the server with the given user and password. Needed only if the SMTP server requires authentication.

s.quit(  )

Terminates the SMTP session.

s.sendmail(from_addr,to_addrs,msg_string)

Sends mail message msg_string from the sender whose email address is in string from_addr to each of the recipients whose email 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, followed by the body. from_addr and to_addrs are used only to direct the mail transport, not to add or change headers within msg_string. To prepare RFC-822-compliant messages, use package email, covered in Chapter 21.