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 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 username => STRING
82 via => CLASS|NAME
83 Attributes
85 $obj->useSSL()
86 Returns "true" when SSL must be used.
87 Receiving mail
89 Extends "Receiving mail" in Mail::Transport::Receive.
90 $obj->receive( [$unique_message_id] )
92 Inherited, see "Receiving mail" in Mail::Transport::Receive
93 Exchanging information
95 $obj->deleteFetched()
96 Mark all messages that have been fetched with message() for
97 deletion. See fetched().
98 $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 $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 $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 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 See also deleteFetched().
124 $obj->folderSize()
126 Returns the total number of octets used by the mailbox on the
127 remote server.
128 $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 The optional integer $bodylines specifies the number of lines from
135 the body which should be added, by default none.
136 example:
138 my $ref_lines = $pop3->header($uidl);
140 print @$ref_lines;
141 $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 $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 $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 example:
159 my $ref_lines = $pop3->message($uidl);
161 print @$ref_lines;
162 $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 $obj->messages()
169 Returns (in scalar context only) the number of messages that are
170 known to exist in the mailbox.
171 Protocol internals
173 The follow methods handle protocol internals, and should not be used by
174 a normal user of this class.
175 $obj->login()
177 Establish a new connection to the POP3 server, using username and
178 password.
179 $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 This method does not attempt to reconnect or anything: if reading
186 or writing the socket fails, something is very definitely wrong.
187 $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 $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 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 $obj->status($socket)
207 Update the current status of folder on the remote POP3 server.
208 Server connection
210 Extends "Server connection" in Mail::Transport::Receive.
211 $obj->findBinary( $name, [@directories] )
213 Inherited, see "Server connection" in Mail::Transport
214 $obj->remoteHost()
216 Inherited, see "Server connection" in Mail::Transport
217 $obj->retry()
219 Inherited, see "Server connection" in Mail::Transport
220 $obj->url()
222 Represent this pop3 connection as URL.
223 Error handling
225 Extends "Error handling" in Mail::Transport::Receive.
226 $obj->AUTOLOAD()
228 Inherited, see "Error handling" in Mail::Reporter
229 $obj->addReport($object)
231 Inherited, see "Error handling" in Mail::Reporter
232 $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 $obj->errors()
240 Inherited, see "Error handling" in Mail::Reporter
241 $obj->log( [$level, [$strings]] )
243 Mail::Transport::POP3->log( [$level, [$strings]] )
244 Inherited, see "Error handling" in Mail::Reporter
245 $obj->logPriority($level)
247 Mail::Transport::POP3->logPriority($level)
248 Inherited, see "Error handling" in Mail::Reporter
249 $obj->logSettings()
251 Inherited, see "Error handling" in Mail::Reporter
252 $obj->notImplemented()
254 Inherited, see "Error handling" in Mail::Reporter
255 $obj->report( [$level] )
257 Inherited, see "Error handling" in Mail::Reporter
258 $obj->reportAll( [$level] )
260 Inherited, see "Error handling" in Mail::Reporter
261 $obj->trace( [$level] )
263 Inherited, see "Error handling" in Mail::Reporter
264 $obj->warnings()
266 Inherited, see "Error handling" in Mail::Reporter
267 Cleanup
269 Extends "Cleanup" in Mail::Transport::Receive.
270 $obj->DESTROY()
272 Inherited, see "Cleanup" in Mail::Reporter
273
275 Error: Cannot connect to $host:$port for POP3: $!
276 Unsuccessful in connecting to the remote POP3 server.
277 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 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 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 Error: Cannot write POP3 to socket: $@
293 It is not possible to send a protocol command to the POP3 server.
294 Connection lost?
295 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 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 Error: POP3 Could not do a STAT
309 For some weird reason, the server does not respond to the STAT
310 call.
311 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 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 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
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
333 Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
334 ChangeLog.
335 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/
338perl v5.38.0 2023-07-20 Mail::Transport::POP3(3)