Mail::Transport::IMAP4(3pm)

1Mail::Transport::IMAP4(U3s)er Contributed Perl DocumentatMiaoinl::Transport::IMAP4(3)
2
3
4

NAME

6       Mail::Transport::IMAP4 - proxy to Mail::IMAPClient
7

INHERITANCE

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

SYNOPSIS

15        my $imap = Mail::Transport::IMAP4->new(...);
16        my $message = $imap->receive($id);
17        $imap->send($message);
18
19        my Mail::Box::Manager $mgr = Mail::Box::Manager->new;
20        $mgr->open(
21            # Generic folder options
22            folder => 'imaps://...',
23            access => 'rw',
24            extract => 'ALWAYS',
25
26            # Mail::IMAPClient options start with [A-Z]
27            IgnoreSizeErrors => 1,
28            Ssl => 1,
29        );
30

DESCRIPTION

32       The IMAP4 protocol is quite complicated: it is feature rich and allows
33       various asynchronous actions.  The main document describing IMAP is
34       rfc3501 (which obsoleted the original specification of protocol 4r1 in
35       rfc2060 in March 2003).
36
37       This package, as part of MailBox, does not implement the actual
38       protocol itself but uses Mail::IMAPClient to do the work. The task for
39       this package is to hide as many differences between that module's
40       interface and the common MailBox folder types.  Multiple
41       Mail::Box::IMAP4 folders can share one Mail::Transport::IMAP4
42       connection.
43
44       The Mail::IMAPClient module is the best IMAP4 implementation for Perl5,
45       but is not maintained.  There are many known problems with the module,
46       and solving those is outside the scope of MailBox.  See
47       http://rt.cpan.org/Public/Dist/Display.html?Name=Mail-IMAPClient for
48       all the reported bugs.
49
50       Extends "DESCRIPTION" in Mail::Transport::Receive.
51

METHODS

53       Extends "METHODS" in Mail::Transport::Receive.
54
55   Constructors
56       Extends "Constructors" in Mail::Transport::Receive.
57
58       Mail::Transport::IMAP4->new(%options)
59           Create the IMAP connection to the server.  IMAP servers can handle
60           multiple folders for a single user, which means that connections
61           may get shared.  This is sharing is hidden for the user.
62
63           When an "imap_client" is specified, then the options "hostname",
64           "port", "username", and "password" are extracted from it.
65
66           All %options which start with a capital are passed as initiation to
67           Mail::IMAPClient.  See that manual about the huge pile of
68           parameters.  When talking to Microsoft Exchange, you probabaly need
69           the "IgnoreSizeErros".  Probably, you need "Ssl" or "StartTLS" as
70           well.  As feature, you may also pass a HASH to Ssl, where
71           "Mail::IMAPClient" only accepts an ARRAY.
72
73           For backwards compatibility, "ssl" is an alternative for "Ssl", and
74           "starttls" for "StartTLS".
75
76            -Option      --Defined in     --Default
77             authenticate                   'AUTO'
78             domain                         <server_name>
79             executable    Mail::Transport  undef
80             hostname      Mail::Transport  'localhost'
81             imap_client                    Mail::IMAPClient
82             interval      Mail::Transport  30
83             log           Mail::Reporter   'WARNINGS'
84             password      Mail::Transport  undef
85             port          Mail::Transport  143
86             proxy         Mail::Transport  undef
87             retry         Mail::Transport  <false>
88             timeout       Mail::Transport  120
89             trace         Mail::Reporter   'WARNINGS'
90             username      Mail::Transport  undef
91             via           Mail::Transport  'imap'
92
93           authenticate => TYPE|ARRAY
94             Authenthication method to login(), which will be passed to
95             Mail::IMAPClient subroutine authenticate.  See the latter method
96             for the available types.  You may provide an ARRAY of types.
97
98           domain => WINDOWS_DOMAIN
99             Used for NTLM authentication.
100
101           executable => FILENAME
102           hostname => HOSTNAME|ARRAY
103           imap_client => OBJECT|CLASS
104             When an OBJECT is supplied, that client will be used for the
105             implementation of the IMAP4 protocol. Information about server
106             and such are extracted from the OBJECT to have the accessors to
107             produce correct results. The OBJECT shall be a Mail::IMAPClient.
108
109             When a CLASS is given, an object of that type is created for you.
110             The created object can be retrieved via imapClient(), and than
111             configured as defined by Mail::IMAPClient.
112
113           interval => SECONDS
114           log => LEVEL
115           password => STRING
116           port => INTEGER
117           proxy => PATH
118           retry => NUMBER|undef
119           timeout => SECONDS
120           trace => LEVEL
121           username => STRING
122           via => CLASS|NAME
123
124   Receiving mail
125       Extends "Receiving mail" in Mail::Transport::Receive.
126
127       $obj->receive( [$unique_message_id] )
128           Inherited, see "Receiving mail" in Mail::Transport::Receive
129
130   Server connection
131       Extends "Server connection" in Mail::Transport::Receive.
132
133       $obj->findBinary( $name, [@directories] )
134           Inherited, see "Server connection" in Mail::Transport
135
136       $obj->remoteHost()
137           Inherited, see "Server connection" in Mail::Transport
138
139       $obj->retry()
140           Inherited, see "Server connection" in Mail::Transport
141
142   Attributes
143       $obj->authentication( ['AUTO'|$type|$types] )
144           Returns a LIST of ARRAYS, each describing one possible way to
145           contact the server. Each pair contains a mechanism name and a
146           challenge callback (which may be "undef").
147
148           The settings are used by login() to get server access.  The initial
149           value origins from new(authenticate), but may be changed later.
150
151           Available basic $types are "CRAM-MD5", "NTLM", and "PLAIN".  With
152           "AUTO", all available types will be tried.  When the Authen::NTLM
153           is not installed, the "NTLM" option will silently be skipped.  Be
154           warned that, because of "PLAIN", erroneous username/password
155           combinations will be passed readible as last attempt!
156
157           The "NTLM" authentication requires Authen::NTLM to be installed.
158           Other methods may be added later.  Besides, you may also specify a
159           CODE reference which implements some authentication.
160
161           An ARRAY as $type can be used to specify both mechanism as
162           callback.  When no array is used, callback of the pair is set to
163           "undef".  See "authenticate" in Mail::IMAPClient for the gory
164           details.
165
166           example:
167
168            $transporter->authentication('CRAM-MD5', [MY_AUTH => \&c], 'PLAIN');
169
170            foreach my $pair ($transporter->authentication)
171            {   my ($mechanism, $challenge) = @$pair;
172                ...
173            }
174
175       $obj->domain( [$domain] )
176           Used in NTLM authentication to define the Windows domain which is
177           accessed.  Initially set by new(domain) and defaults to the
178           server's name.
179
180       $obj->usesSSL()
181           Returns a boolean.
182
183   Exchanging Information
184   Protocol [internals]
185       The follow methods handle protocol internals, and should not be used by
186       a normal user of this class.
187
188       $obj->appendMessage( $message, $foldername, [$date] )
189           Write the message to the server.  The optional DATA can be a
190           RFC-822 date or a timestamp.
191
192       $obj->createFolder($name)
193           Add a folder.
194
195       $obj->createImapClient($class, %options)
196           Create an object of $class, which extends Mail::IMAPClient.
197
198           All %options will be passed to the constructor (new) of $class.
199
200       $obj->currentFolder( [$foldername] )
201           Be sure that the specific FOLDER is the current one selected.  If
202           the folder is already selected, no IMAP traffic will be produced.
203
204           The boolean return value indicates whether the folder is
205           selectable. It will return undef if it does not exist.
206
207       $obj->deleteFolder($name)
208           Remove one folder.
209
210       $obj->destroyDeleted($folder)
211           Command the server to delete for real all messages which are
212           flagged to be deleted.
213
214       $obj->fetch(ARRAY-$of-$messages, $info)
215           Get some $info about the $messages from the server.  The specified
216           messages shall extend Mail::Box::Net::Message, Returned is a list
217           of hashes, each info about one result.  The contents of the hash
218           differs per $info, but at least a "message" field will be present,
219           to relate to the message in question.
220
221           The right folder should be selected before this method is called.
222           When the connection was lost, "undef" is returned.  Without any
223           messages, and empty array is returned.  The retrieval is done by
224           Mail::IMAPClient method "fetch()", which is then parsed.
225
226       $obj->flagsToLabels($what, @flags)
227       Mail::Transport::IMAP4->flagsToLabels($what, @flags)
228           In SCALAR context, a hash with labels is returned.  In LIST
229           context, pairs are returned.
230
231           The $what parameter can be 'SET', 'CLEAR', or 'REPLACE'.  With the
232           latter, all standard imap flags which do not appear in the list
233           will be ignored: their value may either by set or cleared.  See
234           getFlags()
235
236           Unknown flags in @flags are stripped from their backslash and
237           lower-cased.  For instance, '\SomeWeirdFlag' will become
238           `someweirdflag => 1'.  It will be set to '1' for "SET", and '0' in
239           case of "CLEAR".
240
241           example: translating IMAP4 flags into MailBox flags
242
243            my @flags  = ('\Seen', '\Flagged');
244            my $labels = Mail::Transport::IMAP4->flags2labels(SET => @flags);
245
246       $obj->folders( [$foldername] )
247           Returns a list of folder names which are sub-folders of the
248           specified $foldername.  Without $foldername, the top-level
249           foldernames are returned.
250
251       $obj->getFields( $uid, $name, [$name, ...] )
252           Get the records with the specified NAMES from the header.  The
253           header fields are returned as list of Mail::Message::Field::Fast
254           objects.  When the name is "ALL", the whole header is returned.
255
256       $obj->getFlags($folder, $id)
257           Returns the values of all flags which are related to the message
258           with the specified $id.  These flags are translated into the names
259           which are standard for the MailBox suite.
260
261           A HASH is returned.  Names which do not appear will also provide a
262           value in the returned: the negative for the value is it was
263           present.
264
265       $obj->getMessageAsString($message|$uid)
266           Returns the whole text of the specified message: the head and the
267           body.
268
269       $obj->ids()
270           Returns a list of UIDs which are defined by the IMAP server.
271
272       $obj->imapClient()
273           Returns the object which implements the IMAP4 protocol, an instance
274           of a Mail::IMAPClient, which is logged-in and ready to use.
275
276           If the contact to the server was still present or could be
277           established, an Mail::IMAPClient object is returned.  Else, "undef"
278           is returned and no further actions should be tried on the object.
279
280       $obj->labelsToFlags(HASH|PAIRS)
281       Mail::Transport::IMAP4->labelsToFlags(HASH|PAIRS)
282           Convert MailBox labels into IMAP flags.  Returned is a string.
283           Unsupported labels are ignored.
284
285       $obj->listFlags()
286           Returns all predefined flags as list.
287
288       $obj->login()
289           Establish a new connection to the IMAP4 server, using username and
290           password.
291
292       $obj->setFlags($id, $label, $value, [$label, $value], ...)
293           Change the flags on the message which are represented by the label.
294           The value which can be related to the label will be lost, because
295           IMAP only defines a boolean value, where MailBox labels can contain
296           strings.
297
298           Returned is a list of $label=>$value pairs which could not be send
299           to the IMAP server.  These values may be cached in a different way.
300
301   Error handling
302       Extends "Error handling" in Mail::Transport::Receive.
303
304       $obj->AUTOLOAD()
305           Inherited, see "Error handling" in Mail::Reporter
306
307       $obj->addReport($object)
308           Inherited, see "Error handling" in Mail::Reporter
309
310       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
311       $callback] )
312       Mail::Transport::IMAP4->defaultTrace( [$level]|[$loglevel,
313       $tracelevel]|[$level, $callback] )
314           Inherited, see "Error handling" in Mail::Reporter
315
316       $obj->errors()
317           Inherited, see "Error handling" in Mail::Reporter
318
319       $obj->log( [$level, [$strings]] )
320       Mail::Transport::IMAP4->log( [$level, [$strings]] )
321           Inherited, see "Error handling" in Mail::Reporter
322
323       $obj->logPriority($level)
324       Mail::Transport::IMAP4->logPriority($level)
325           Inherited, see "Error handling" in Mail::Reporter
326
327       $obj->logSettings()
328           Inherited, see "Error handling" in Mail::Reporter
329
330       $obj->notImplemented()
331           Inherited, see "Error handling" in Mail::Reporter
332
333       $obj->report( [$level] )
334           Inherited, see "Error handling" in Mail::Reporter
335
336       $obj->reportAll( [$level] )
337           Inherited, see "Error handling" in Mail::Reporter
338
339       $obj->trace( [$level] )
340           Inherited, see "Error handling" in Mail::Reporter
341
342       $obj->warnings()
343           Inherited, see "Error handling" in Mail::Reporter
344
345   Cleanup
346       Extends "Cleanup" in Mail::Transport::Receive.
347
348       $obj->DESTROY()
349           The connection is cleanly terminated when the program is
350           terminated.
351

DIAGNOSTICS

353       Error: Cannot connect to $host:$port for IMAP4: $!
354       Error: IMAP cannot connect to $host: $@
355       Notice: IMAP4 authenication $mechanism to $host:$port successful
356       Error: IMAP4 requires a username and password
357       Error: IMAP4 username $username requires a password
358       Error: Package $package does not implement $method.
359           Fatal error: the specific package (or one of its superclasses) does
360           not implement this method where it should. This message means that
361           some other related classes do implement this method however the
362           class at hand does not.  Probably you should investigate this and
363           probably inform the author of the package.
364

LICENSE

370       Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
371       ChangeLog.
372
373       This program is free software; you can redistribute it and/or modify it
374       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
375
376
377
378perl v5.34.0                      2021-07-22         Mail::Transport::IMAP4(3)