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

DESCRIPTION

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

METHODS

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

DIAGNOSTICS

333       Error: Cannot connect to $host:$port for IMAP4: $!
334       Error: IMAP cannot connect to $host: $@
335       Notice: IMAP4 authenication $mechanism to $host:$port successful
336       Error: IMAP4 requires a username and password
337       Error: IMAP4 username $username requires a password
338       Error: Package $package does not implement $method.
339           Fatal error: the specific package (or one of its superclasses) does
340           not implement this method where it should. This message means that
341           some other related classes do implement this method however the
342           class at hand does not.  Probably you should investigate this and
343           probably inform the author of the package.
344

LICENSE

350       Copyrights 2001-2018 by [Mark Overmeer]. For other contributors see
351       ChangeLog.
352
353       This program is free software; you can redistribute it and/or modify it
354       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
355
356
357
358perl v5.28.0                      2018-03-04         Mail::Transport::IMAP4(3)