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
20       specified in rfc1939.  This object hides much of the complications in
21       the protocol and recovers broken connections automatically.  Although
22       it is part of the MailBox distribution, this object can be used
23       separately.
24
25       You probably should not use this module, but Mail::Box::POP3.  This
26       module is the interface to POP3, whereas Mail::Box::POP3 hides the
27       protocol weirdness and works as any other mail folder.
28
29       Extends "DESCRIPTION" in Mail::Transport::Receive.
30

METHODS

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

DIAGNOSTICS

275       Error: Cannot connect to $host:$port for POP3: $!
276           Unsuccessful in connecting to the remote POP3 server.
277
278       Error: Cannot get the messages of pop3 via messages()
279           It is not possible to retrieve all messages on a remote POP3 folder
280           at once: each shall be taken separately.  The POP3 folder will hide
281           this for you.
282
283       Error: Cannot re-connect reliably to server which doesn't support UIDL.
284           The connection to the remote POP3 was lost, and cannot be re-
285           established because the server's protocol implementation lacks the
286           necessary information.
287
288       Error: Cannot read POP3 from socket: $!
289           It is not possible to read the success status of the previously
290           given POP3 command.  Connection lost?
291
292       Error: Cannot write POP3 to socket: $@
293           It is not possible to send a protocol command to the POP3 server.
294           Connection lost?
295
296       Error: Could not authenticate using '$some' method.
297           The authenication method to get access to the POP3 server did not
298           result in a connection.  Maybe you need a different authentication
299           protocol, or your username with password are invalid.
300
301       Error: Could not authenticate using any login method.
302           No authentication method was explicitly prescribed, so both AUTH
303           and APOP were tried.  However, both failed.  There are other
304           authentication methods, which are not defined by the main POP3 RFC
305           rfc1939.  These protocols are not implemented yet.  Please
306           contribute your implementation.
307
308       Error: POP3 Could not do a STAT
309           For some weird reason, the server does not respond to the STAT
310           call.
311
312       Error: POP3 requires a username and password.
313           No username and/or no password specified for this POP3 folder,
314           although these are obligatory parts in the protocol.
315
316       Error: Package $package does not implement $method.
317           Fatal error: the specific package (or one of its superclasses) does
318           not implement this method where it should. This message means that
319           some other related classes do implement this method however the
320           class at hand does not.  Probably you should investigate this and
321           probably inform the author of the package.
322
323       Error: Server at $host:$port does not seem to be talking POP3.
324           The remote server did not respond to an initial exchange of
325           messages as is expected by the POP3 protocol.  The server has
326           probably a different service on the specified port.
327

SEE ALSO

329       This module is part of Mail-Box-POP3 distribution version 3.005, built
330       on May 03, 2019. Website: http://perl.overmeer.net/CPAN/
331

LICENSE

333       Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
334       ChangeLog.
335
336       This program is free software; you can redistribute it and/or modify it
337       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
338
339
340
341perl v5.38.0                      2023-07-20          Mail::Transport::POP3(3)
Impressum