1:mod:`poplib` --- POP3 protocol client
2======================================
3
4.. module:: poplib
5   :synopsis: POP3 protocol client (requires sockets).
6
7.. sectionauthor:: Andrew T. Csillag
8.. revised by ESR, January 2000
9
10**Source code:** :source:`Lib/poplib.py`
11
12.. index:: pair: POP3; protocol
13
14--------------
15
16This module defines a class, :class:`POP3`, which encapsulates a connection to a
17POP3 server and implements the protocol as defined in :rfc:`1939`. The
18:class:`POP3` class supports both the minimal and optional command sets from
19:rfc:`1939`. The :class:`POP3` class also supports the ``STLS`` command introduced
20in :rfc:`2595` to enable encrypted communication on an already established connection.
21
22Additionally, this module provides a class :class:`POP3_SSL`, which provides
23support for connecting to POP3 servers that use SSL as an underlying protocol
24layer.
25
26Note that POP3, though widely supported, is obsolescent.  The implementation
27quality of POP3 servers varies widely, and too many are quite poor. If your
28mailserver supports IMAP, you would be better off using the
29:class:`imaplib.IMAP4` class, as IMAP servers tend to be better implemented.
30
31The :mod:`poplib` module provides two classes:
32
33
34.. class:: POP3(host, port=POP3_PORT[, timeout])
35
36   This class implements the actual POP3 protocol.  The connection is created when
37   the instance is initialized. If *port* is omitted, the standard POP3 port (110)
38   is used. The optional *timeout* parameter specifies a timeout in seconds for the
39   connection attempt (if not specified, the global default timeout setting will
40   be used).
41
42   .. audit-event:: poplib.connect self,host,port poplib.POP3
43
44   .. audit-event:: poplib.putline self,line poplib.POP3
45
46      All commands will raise an :ref:`auditing event <auditing>`
47      ``poplib.putline`` with arguments ``self`` and ``line``,
48      where ``line`` is the bytes about to be sent to the remote host.
49
50
51.. class:: POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)
52
53   This is a subclass of :class:`POP3` that connects to the server over an SSL
54   encrypted socket.  If *port* is not specified, 995, the standard POP3-over-SSL
55   port is used.  *timeout* works as in the :class:`POP3` constructor.
56   *context* is an optional :class:`ssl.SSLContext` object which allows
57   bundling SSL configuration options, certificates and private keys into a
58   single (potentially long-lived) structure.  Please read :ref:`ssl-security`
59   for best practices.
60
61   *keyfile* and *certfile* are a legacy alternative to *context* - they can
62   point to PEM-formatted private key and certificate chain files,
63   respectively, for the SSL connection.
64
65   .. audit-event:: poplib.connect self,host,port poplib.POP3_SSL
66
67   .. audit-event:: poplib.putline self,line poplib.POP3_SSL
68
69      All commands will raise an :ref:`auditing event <auditing>`
70      ``poplib.putline`` with arguments ``self`` and ``line``,
71      where ``line`` is the bytes about to be sent to the remote host.
72
73   .. versionchanged:: 3.2
74      *context* parameter added.
75
76   .. versionchanged:: 3.4
77      The class now supports hostname check with
78      :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
79      :data:`ssl.HAS_SNI`).
80
81   .. deprecated:: 3.6
82
83       *keyfile* and *certfile* are deprecated in favor of *context*.
84       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
85       :func:`ssl.create_default_context` select the system's trusted CA
86       certificates for you.
87
88One exception is defined as an attribute of the :mod:`poplib` module:
89
90
91.. exception:: error_proto
92
93   Exception raised on any errors from this module (errors from :mod:`socket`
94   module are not caught). The reason for the exception is passed to the
95   constructor as a string.
96
97
98.. seealso::
99
100   Module :mod:`imaplib`
101      The standard Python IMAP module.
102
103   `Frequently Asked Questions About Fetchmail <http://www.catb.org/~esr/fetchmail/fetchmail-FAQ.html>`_
104      The FAQ for the :program:`fetchmail` POP/IMAP client collects information on
105      POP3 server variations and RFC noncompliance that may be useful if you need to
106      write an application based on the POP protocol.
107
108
109.. _pop3-objects:
110
111POP3 Objects
112------------
113
114All POP3 commands are represented by methods of the same name, in lower-case;
115most return the response text sent by the server.
116
117An :class:`POP3` instance has the following methods:
118
119
120.. method:: POP3.set_debuglevel(level)
121
122   Set the instance's debugging level.  This controls the amount of debugging
123   output printed.  The default, ``0``, produces no debugging output.  A value of
124   ``1`` produces a moderate amount of debugging output, generally a single line
125   per request.  A value of ``2`` or higher produces the maximum amount of
126   debugging output, logging each line sent and received on the control connection.
127
128
129.. method:: POP3.getwelcome()
130
131   Returns the greeting string sent by the POP3 server.
132
133
134.. method:: POP3.capa()
135
136   Query the server's capabilities as specified in :rfc:`2449`.
137   Returns a dictionary in the form ``{'name': ['param'...]}``.
138
139   .. versionadded:: 3.4
140
141
142.. method:: POP3.user(username)
143
144   Send user command, response should indicate that a password is required.
145
146
147.. method:: POP3.pass_(password)
148
149   Send password, response includes message count and mailbox size. Note: the
150   mailbox on the server is locked until :meth:`~poplib.quit` is called.
151
152
153.. method:: POP3.apop(user, secret)
154
155   Use the more secure APOP authentication to log into the POP3 server.
156
157
158.. method:: POP3.rpop(user)
159
160   Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
161
162
163.. method:: POP3.stat()
164
165   Get mailbox status.  The result is a tuple of 2 integers: ``(message count,
166   mailbox size)``.
167
168
169.. method:: POP3.list([which])
170
171   Request message list, result is in the form ``(response, ['mesg_num octets',
172   ...], octets)``. If *which* is set, it is the message to list.
173
174
175.. method:: POP3.retr(which)
176
177   Retrieve whole message number *which*, and set its seen flag. Result is in form
178   ``(response, ['line', ...], octets)``.
179
180
181.. method:: POP3.dele(which)
182
183   Flag message number *which* for deletion.  On most servers deletions are not
184   actually performed until QUIT (the major exception is Eudora QPOP, which
185   deliberately violates the RFCs by doing pending deletes on any disconnect).
186
187
188.. method:: POP3.rset()
189
190   Remove any deletion marks for the mailbox.
191
192
193.. method:: POP3.noop()
194
195   Do nothing.  Might be used as a keep-alive.
196
197
198.. method:: POP3.quit()
199
200   Signoff:  commit changes, unlock mailbox, drop connection.
201
202
203.. method:: POP3.top(which, howmuch)
204
205   Retrieves the message header plus *howmuch* lines of the message after the
206   header of message number *which*. Result is in form ``(response, ['line', ...],
207   octets)``.
208
209   The POP3 TOP command this method uses, unlike the RETR command, doesn't set the
210   message's seen flag; unfortunately, TOP is poorly specified in the RFCs and is
211   frequently broken in off-brand servers. Test this method by hand against the
212   POP3 servers you will use before trusting it.
213
214
215.. method:: POP3.uidl(which=None)
216
217   Return message digest (unique id) list. If *which* is specified, result contains
218   the unique id for that message in the form ``'response mesgnum uid``, otherwise
219   result is list ``(response, ['mesgnum uid', ...], octets)``.
220
221
222.. method:: POP3.utf8()
223
224   Try to switch to UTF-8 mode. Returns the server response if successful,
225   raises :class:`error_proto` if not. Specified in :RFC:`6856`.
226
227   .. versionadded:: 3.5
228
229
230.. method:: POP3.stls(context=None)
231
232   Start a TLS session on the active connection as specified in :rfc:`2595`.
233   This is only allowed before user authentication
234
235   *context* parameter is a :class:`ssl.SSLContext` object which allows
236   bundling SSL configuration options, certificates and private keys into
237   a single (potentially long-lived) structure.  Please read :ref:`ssl-security`
238   for best practices.
239
240   This method supports hostname checking via
241   :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
242   :data:`ssl.HAS_SNI`).
243
244   .. versionadded:: 3.4
245
246
247Instances of :class:`POP3_SSL` have no additional methods. The interface of this
248subclass is identical to its parent.
249
250
251.. _pop3-example:
252
253POP3 Example
254------------
255
256Here is a minimal example (without error checking) that opens a mailbox and
257retrieves and prints all messages::
258
259   import getpass, poplib
260
261   M = poplib.POP3('localhost')
262   M.user(getpass.getuser())
263   M.pass_(getpass.getpass())
264   numMessages = len(M.list()[1])
265   for i in range(numMessages):
266       for j in M.retr(i+1)[1]:
267           print(j)
268
269At the end of the module, there is a test section that contains a more extensive
270example of usage.
271
272