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