Mail::Transport::POP3(3pm)

1Mail::Transport::POP3(3U)ser Contributed Perl DocumentatiMoanil::Transport::POP3(3)
2
3
4

NAME

6       Mail::Transport::POP3 - receive messages via POP3
7

INHERITANCE

9        Mail::Transport::POP3
10          is a Mail::Transport::Receive
11          is a Mail::Transport
12          is a Mail::Reporter
13

SYNOPSIS

15        my $receiver = Mail::Transport::POP3->new(...);
16        my $message = $receiver->receive($id);
17

DESCRIPTION

19       Receive messages via the POP3 protocol from one remote server, as spec‐
20       ified in rfc1939.  This object hides much of the complications in the
21       protocol and recovers broken connections automatically.  Although it is
22       part of the MailBox distribution, this object can be used separately.
23
24       You probably should not use this module, but Mail::Box::POP3.  This
25       module is the interface to POP3, whereas Mail::Box::POP3 hides the pro‐
26       tocol weirdness and works as any other mail folder.
27

METHODS

29       Constructors
30
31       Mail::Transport::POP3->new(OPTIONS)
32
33           Create a new pop3 server connection.  One object can only handle
34           one connection: for a single user to one single server.  If the
35           server could not be reached, or when the login fails, this instan‐
36           tiating "new" will return "undef".
37
38            Option      --Defined in     --Default
39            authenticate                   'AUTO'
40            executable    Mail::Transport  undef
41            hostname      Mail::Transport  'localhost'
42            interval      Mail::Transport  30
43            log           Mail::Reporter   'WARNINGS'
44            password      Mail::Transport  undef
45            port          Mail::Transport  110
46            proxy         Mail::Transport  undef
47            retry         Mail::Transport  <false>
48            timeout       Mail::Transport  120
49            trace         Mail::Reporter   'WARNINGS'
50            username      Mail::Transport  undef
51            via           Mail::Transport  'sendmail'
52
53           . authenticate 'LOGIN'⎪'APOP'⎪'AUTO'
54
55               Authenthication method.  The standard defines two methods,
56               named LOGIN and APOP.  The first sends the username and pass‐
57               word in plain text to the server to get permission, the latter
58               encrypts this data using MD5.  When AUTO is used, first APOP is
59               tried, and then LOGIN.
60
61           . executable FILENAME
62
63           . hostname HOSTNAME⎪ARRAY-OF-HOSTNAMES
64
65           . interval SECONDS
66
67           . log LEVEL
68
69           . password STRING
70
71           . port INTEGER
72
73           . proxy PATH
74
75           . retry NUMBER⎪undef
76
77           . timeout SECONDS
78
79           . trace LEVEL
80
81           . username STRING
82
83           . via CLASS⎪NAME
84
85       Receiving mail
86
87       $obj->receive([UNIQUE-MESSAGE-ID])
88
89           See "Receiving mail" in Mail::Transport::Receive
90
91       Exchanging information
92
93       $obj->deleteFetched
94
95           Mark all messages that have been fetched with message() for dele‐
96           tion.  See fetched().
97
98       $obj->deleted(BOOLEAN, ID's)
99
100           Either mark the specified message(s) to be deleted on the remote
101           server or unmark them for deletion (if the first parameter is
102           false).  Deletion of messages will take place only when the connec‐
103           tion is specifically disconnected or the last reference to the
104           object goes out of scope.
105
106       $obj->disconnect
107
108           Break contact with the server, if that (still) exists.  Returns
109           true if successful.  Please note that even if the disconnect was
110           not successful, all knowledge of messages etc. will be removed from
111           the object: the object basically has reverted to the state in which
112           it was before anything was done with the mail box.
113
114       $obj->fetched
115
116           Returns a reference to a list of ID's that have been fetched using
117           message().  This can be used to update a database of messages that
118           were fetched (but maybe not yet deleted) from the mailbox.
119
120           Please note that if the POP3 server did not support the UIDL com‐
121           mand, this method will always return undef because it is not possi‐
122           bly to reliably identify messages between sessions (other than
123           looking at the contents of the messages themselves).
124
125           See also deleteFetched().
126
127       $obj->folderSize
128
129           Returns the total number of octets used by the mailbox on the
130           remote server.
131
132       $obj->header(ID, [BODYLINES])
133
134           Returns a reference to an array which contains the header of the
135           message with the specified ID.  "undef" is returned if something
136           has gone wrong.
137
138           The optional integer BODYLINES specifies the number of lines from
139           the body which should be added, by default none.
140
141           Example:
142
143            my $ref_lines = $pop3->header($uidl);
144            print @$ref_lines;
145
146       $obj->id2n(ID)
147
148           Translates the unique ID of a message into a sequence number which
149           represents the message as long a this connection to the POP3 server
150           exists.  When the message has been deleted for some reason, "undef"
151           is returned.
152
153       $obj->ids
154
155           Returns a list (in list context) or a reference to a list (in
156           scalar context) of all ID's which are known by the server on this
157           moment.
158
159       $obj->message(ID)
160
161           Returns a reference to an array which contains the lines of the
162           message with the specified ID.  Returns "undef" if something has
163           gone wrong.
164
165           Example:
166
167            my $ref_lines = $pop3->message($uidl);
168            print @$ref_lines;
169
170       $obj->messageSize(ID)
171
172           Returns the size of the message which is indicated by the ID, in
173           octets.  If the message has been deleted on the remote server, this
174           will return "undef".
175
176       $obj->messages
177
178           Returns (in scalar context only) the number of messages that are
179           known to exist in the mailbox.
180
181       Protocol internals
182
183       The follow methods handle protocol internals, and should not be used by
184       a normal user of this class.
185
186       $obj->login
187
188           Establish a new connection to the POP3 server, using username and
189           password.
190
191       $obj->send(SOCKET, data)
192
193           Send data to the indicated socket and return the first line read
194           from that socket.  Logs an error if either writing to or reading
195           from socket failed.
196
197           This method does not attempt to reconnect or anything: if reading
198           or writing the socket fails, something is very definitely wrong.
199
200       $obj->sendList(SOCKET, COMMAND)
201
202           Sends the indicated COMMAND to the specified socket, and retrieves
203           the response.  It returns a reference to an array with all the
204           lines that were reveived after the first "+OK" line and before the
205           end-of-message delimiter (a single dot on a line).  Returns "undef"
206           whenever something has gone wrong.
207
208       $obj->socket
209
210           Returns a connection to the POP3 server.  If there was no connec‐
211           tion yet, it will be created transparently.  If the connection with
212           the POP3 server was lost, it will be reconnected and the assures
213           that internal state information (STAT and UIDL) is up-to-date in
214           the object.
215
216           If the contact to the server was still present, or could be estab‐
217           lished, an IO::Socket::INET object is returned.  Else, "undef" is
218           returned and no further actions should be tried on the object.
219
220       $obj->status(SOCKET)
221
222           Update the current status of folder on the remote POP3 server.
223
224       Server connection
225
226       $obj->findBinary(NAME [, DIRECTORIES])
227
228           See "Server connection" in Mail::Transport
229
230       $obj->remoteHost
231
232           See "Server connection" in Mail::Transport
233
234       $obj->retry
235
236           See "Server connection" in Mail::Transport
237
238       $obj->url
239
240           Represent this pop3 connection as URL.
241
242       Error handling
243
244       $obj->AUTOLOAD
245
246           See "Error handling" in Mail::Reporter
247
248       $obj->addReport(OBJECT)
249
250           See "Error handling" in Mail::Reporter
251
252       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
253
254       Mail::Transport::POP3->defaultTrace([LEVEL]⎪[LOGLEVEL,
255       TRACELEVEL]⎪[LEVEL, CALLBACK])
256
257           See "Error handling" in Mail::Reporter
258
259       $obj->errors
260
261           See "Error handling" in Mail::Reporter
262
263       $obj->log([LEVEL [,STRINGS]])
264
265       Mail::Transport::POP3->log([LEVEL [,STRINGS]])
266
267           See "Error handling" in Mail::Reporter
268
269       $obj->logPriority(LEVEL)
270
271       Mail::Transport::POP3->logPriority(LEVEL)
272
273           See "Error handling" in Mail::Reporter
274
275       $obj->logSettings
276
277           See "Error handling" in Mail::Reporter
278
279       $obj->notImplemented
280
281           See "Error handling" in Mail::Reporter
282
283       $obj->report([LEVEL])
284
285           See "Error handling" in Mail::Reporter
286
287       $obj->reportAll([LEVEL])
288
289           See "Error handling" in Mail::Reporter
290
291       $obj->trace([LEVEL])
292
293           See "Error handling" in Mail::Reporter
294
295       $obj->warnings
296
297           See "Error handling" in Mail::Reporter
298
299       Cleanup
300
301       $obj->DESTROY
302
303           See "Cleanup" in Mail::Reporter
304
305       $obj->inGlobalDestruction
306
307           See "Cleanup" in Mail::Reporter
308

DIAGNOSTICS

310       Error: Cannot connect to $host:$port for POP3: $!
311
312       Unsuccesful in connecting to the remote POP3 server.
313
314       Error: Cannot get the messages of pop3 via messages()
315
316       It is not possible to retreive all messages on a remote POP3 folder at
317       once: each shall be taken separately.  The POP3 folder will hide this
318       for you.
319
320       Error: Cannot re-connect reliably to server which doesn't support UIDL.
321
322       The connection to the remote POP3 was lost, and cannot be re-estab‐
323       lished because the server's protocol implementation lacks the necessary
324       information.
325
326       Error: Cannot read POP3 from socket: $!
327
328       It is not possible to read the success status of the previously given
329       POP3 command.  Connection lost?
330
331       Error: Cannot write POP3 to socket: $@
332
333       It is not possible to send a protocol command to the POP3 server.  Con‐
334       nection lost?
335
336       Error: Could not authenticate using '$some' method.
337
338       The authenication method to get access to the POP3 server did not
339       result in a connection.  Maybe you need a different authentication pro‐
340       tocol, or your username with password are invalid.
341
342       Error: Could not authenticate using any login method.
343
344       No authentication method was explicitly prescribed, so both AUTH and
345       APOP were tried.  However, both failed.  There are other authentication
346       methods, which are not defined by the main POP3 RFC rfc1939.  These
347       protocols are not implemented yet.  Please contribute your implementa‐
348       tion.
349
350       Error: POP3 Could not do a STAT
351
352       For some weird reason, the server does not respond to the STAT call.
353
354       Error: POP3 requires a username and password.
355
356       No username and/or no password specified for this POP3 folder, although
357       these are obligatory parts in the protocol.
358
359       Error: Package $package does not implement $method.
360
361       Fatal error: the specific package (or one of its superclasses) does not
362       implement this method where it should. This message means that some
363       other related classes do implement this method however the class at
364       hand does not.  Probably you should investigate this and probably
365       inform the author of the package.
366
367       Error: Server at $host:$port does not seem to be talking POP3.
368
369       The remote server did not respond to an initial exchange of messages as
370       is expected by the POP3 protocol.  The server has probably a different
371       service on the specified port.
372

LICENSE

378       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
379       ChangeLog.
380
381       This program is free software; you can redistribute it and/or modify it
382       under the same terms as Perl itself.  See
383       http://www.perl.com/perl/misc/Artistic.html
384
385
386
387perl v5.8.8                       2007-03-25          Mail::Transport::POP3(3)