1Mail::Transport::POP3(3U)ser Contributed Perl DocumentatiMoanil::Transport::POP3(3)
2
6 Mail::Transport::POP3 - receive messages via POP3
7
9 Mail::Transport::POP3
10 is a Mail::Transport::Receive
11 is a Mail::Transport
12 is a Mail::Reporter
13
15 my $receiver = Mail::Transport::POP3->new(...);
16 my $message = $receiver->receive($id);
17
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 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 Extends "DESCRIPTION" in Mail::Transport::Receive.
30
32 Extends "METHODS" in Mail::Transport::Receive.
33 Constructors
35 Extends "Constructors" in Mail::Transport::Receive.
36 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 -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 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 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 username => STRING
78 via => CLASS|NAME
79 Receiving mail
81 Extends "Receiving mail" in Mail::Transport::Receive.
82 $obj->receive( [$unique_message_id] )
84 Inherited, see "Receiving mail" in Mail::Transport::Receive
85 Exchanging information
87 $obj->deleteFetched()
88 Mark all messages that have been fetched with message() for
89 deletion. See fetched().
90 $obj->deleted(BOOLEAN, @ids)
92 Either mark the specified message(s) to be deleted on the remote
93 server or unmark them for deletion (if the first parameter is
94 false). Deletion of messages will take place only when the
95 connection is specifically disconnected or the last reference to
96 the object goes out of scope.
97 $obj->disconnect()
99 Break contact with the server, if that (still) exists. Returns
100 true if successful. Please note that even if the disconnect was
101 not successful, all knowledge of messages etc. will be removed from
102 the object: the object basically has reverted to the state in which
103 it was before anything was done with the mail box.
104 $obj->fetched()
106 Returns a reference to a list of ID's that have been fetched using
107 message(). This can be used to update a database of messages that
108 were fetched (but maybe not yet deleted) from the mailbox.
109 Please note that if the POP3 server did not support the UIDL
111 command, this method will always return undef because it is not
112 possibly to reliably identify messages between sessions (other than
113 looking at the contents of the messages themselves).
114 See also deleteFetched().
116 $obj->folderSize()
118 Returns the total number of octets used by the mailbox on the
119 remote server.
120 $obj->header( $id, [$bodylines] )
122 Returns a reference to an array which contains the header of the
123 message with the specified $id. "undef" is returned if something
124 has gone wrong.
125 The optional integer $bodylines specifies the number of lines from
127 the body which should be added, by default none.
128 example:
130 my $ref_lines = $pop3->header($uidl);
132 print @$ref_lines;
133 $obj->id2n($id)
135 Translates the unique $id of a message into a sequence number which
136 represents the message as long a this connection to the POP3 server
137 exists. When the message has been deleted for some reason, "undef"
138 is returned.
139 $obj->ids()
141 Returns a list (in list context) or a reference to a list (in
142 scalar context) of all IDs which are known by the server on this
143 moment.
144 $obj->message($id)
146 Returns a reference to an array which contains the lines of the
147 message with the specified $id. Returns "undef" if something has
148 gone wrong.
149 example:
151 my $ref_lines = $pop3->message($uidl);
153 print @$ref_lines;
154 $obj->messageSize($id)
156 Returns the size of the message which is indicated by the $id, in
157 octets. If the message has been deleted on the remote server, this
158 will return "undef".
159 $obj->messages()
161 Returns (in scalar context only) the number of messages that are
162 known to exist in the mailbox.
163 Protocol internals
165 The follow methods handle protocol internals, and should not be used by
166 a normal user of this class.
167 $obj->login()
169 Establish a new connection to the POP3 server, using username and
170 password.
171 $obj->send($socket, $data)
173 Send $data to the indicated socket and return the first line read
174 from that socket. Logs an error if either writing to or reading
175 from socket failed.
176 This method does not attempt to reconnect or anything: if reading
178 or writing the socket fails, something is very definitely wrong.
179 $obj->sendList($socket, $command)
181 Sends the indicated $command to the specified socket, and retrieves
182 the response. It returns a reference to an array with all the
183 lines that were reveived after the first "+OK" line and before the
184 end-of-message delimiter (a single dot on a line). Returns "undef"
185 whenever something has gone wrong.
186 $obj->socket()
188 Returns a connection to the POP3 server. If there was no
189 connection yet, it will be created transparently. If the
190 connection with the POP3 server was lost, it will be reconnected
191 and the assures that internal state information (STAT and UIDL) is
192 up-to-date in the object.
193 If the contact to the server was still present, or could be
195 established, an IO::Socket::INET object is returned. Else, "undef"
196 is returned and no further actions should be tried on the object.
197 $obj->status($socket)
199 Update the current status of folder on the remote POP3 server.
200 Server connection
202 Extends "Server connection" in Mail::Transport::Receive.
203 $obj->findBinary( $name, [@directories] )
205 Inherited, see "Server connection" in Mail::Transport
206 $obj->remoteHost()
208 Inherited, see "Server connection" in Mail::Transport
209 $obj->retry()
211 Inherited, see "Server connection" in Mail::Transport
212 $obj->url()
214 Represent this pop3 connection as URL.
215 Error handling
217 Extends "Error handling" in Mail::Transport::Receive.
218 $obj->AUTOLOAD()
220 Inherited, see "Error handling" in Mail::Reporter
221 $obj->addReport($object)
223 Inherited, see "Error handling" in Mail::Reporter
224 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
226 $callback] )
227 Mail::Transport::POP3->defaultTrace( [$level]|[$loglevel,
228 $tracelevel]|[$level, $callback] )
229 Inherited, see "Error handling" in Mail::Reporter
230 $obj->errors()
232 Inherited, see "Error handling" in Mail::Reporter
233 $obj->log( [$level, [$strings]] )
235 Mail::Transport::POP3->log( [$level, [$strings]] )
236 Inherited, see "Error handling" in Mail::Reporter
237 $obj->logPriority($level)
239 Mail::Transport::POP3->logPriority($level)
240 Inherited, see "Error handling" in Mail::Reporter
241 $obj->logSettings()
243 Inherited, see "Error handling" in Mail::Reporter
244 $obj->notImplemented()
246 Inherited, see "Error handling" in Mail::Reporter
247 $obj->report( [$level] )
249 Inherited, see "Error handling" in Mail::Reporter
250 $obj->reportAll( [$level] )
252 Inherited, see "Error handling" in Mail::Reporter
253 $obj->trace( [$level] )
255 Inherited, see "Error handling" in Mail::Reporter
256 $obj->warnings()
258 Inherited, see "Error handling" in Mail::Reporter
259 Cleanup
261 Extends "Cleanup" in Mail::Transport::Receive.
262 $obj->DESTROY()
264 Inherited, see "Cleanup" in Mail::Reporter
265
267 Error: Cannot connect to $host:$port for POP3: $!
268 Unsuccessful in connecting to the remote POP3 server.
269 Error: Cannot get the messages of pop3 via messages()
271 It is not possible to retrieve all messages on a remote POP3 folder
272 at once: each shall be taken separately. The POP3 folder will hide
273 this for you.
274 Error: Cannot re-connect reliably to server which doesn't support UIDL.
276 The connection to the remote POP3 was lost, and cannot be re-
277 established because the server's protocol implementation lacks the
278 necessary information.
279 Error: Cannot read POP3 from socket: $!
281 It is not possible to read the success status of the previously
282 given POP3 command. Connection lost?
283 Error: Cannot write POP3 to socket: $@
285 It is not possible to send a protocol command to the POP3 server.
286 Connection lost?
287 Error: Could not authenticate using '$some' method.
289 The authenication method to get access to the POP3 server did not
290 result in a connection. Maybe you need a different authentication
291 protocol, or your username with password are invalid.
292 Error: Could not authenticate using any login method.
294 No authentication method was explicitly prescribed, so both AUTH
295 and APOP were tried. However, both failed. There are other
296 authentication methods, which are not defined by the main POP3 RFC
297 rfc1939. These protocols are not implemented yet. Please
298 contribute your implementation.
299 Error: POP3 Could not do a STAT
301 For some weird reason, the server does not respond to the STAT
302 call.
303 Error: POP3 requires a username and password.
305 No username and/or no password specified for this POP3 folder,
306 although these are obligatory parts in the protocol.
307 Error: Package $package does not implement $method.
309 Fatal error: the specific package (or one of its superclasses) does
310 not implement this method where it should. This message means that
311 some other related classes do implement this method however the
312 class at hand does not. Probably you should investigate this and
313 probably inform the author of the package.
314 Error: Server at $host:$port does not seem to be talking POP3.
316 The remote server did not respond to an initial exchange of
317 messages as is expected by the POP3 protocol. The server has
318 probably a different service on the specified port.
319
321 This module is part of Mail-Box-POP3 distribution version 3.004, built
322 on March 04, 2018. Website: http://perl.overmeer.net/CPAN/
323
325 Copyrights 2001-2018 by [Mark Overmeer]. For other contributors see
326 ChangeLog.
327 This program is free software; you can redistribute it and/or modify it
329 under the same terms as Perl itself. See http://dev.perl.org/licenses/
330perl v5.28.1 2018-03-04 Mail::Transport::POP3(3)