1=encoding utf8
2
3=head1 NAME
4
5Mail::Box::Net::Message - one message from a distant folder
6
7=head1 INHERITANCE
8
9 Mail::Box::Net::Message
10   is a Mail::Box::Message
11   is a Mail::Message
12   is a Mail::Reporter
13
14 Mail::Box::Net::Message is extended by
15   Mail::Box::IMAP4::Message
16   Mail::Box::POP3::Message
17
18=head1 SYNOPSIS
19
20 my $folder = new Mail::Box::POP3 ...
21 my $message = $folder->message(10);
22
23=head1 DESCRIPTION
24
25A L<Mail::Box::Net::Message|Mail::Box::Net::Message> represents one message in a folder which
26can only be accessed via some kind of protocol.  On this moment, only
27a POP3 client is available.  IMAP, DBI, and NNTP are other candidates.
28
29Extends L<"DESCRIPTION" in Mail::Box::Message|Mail::Box::Message/"DESCRIPTION">.
30
31=head1 METHODS
32
33Extends L<"METHODS" in Mail::Box::Message|Mail::Box::Message/"METHODS">.
34
35=head2 Constructors
36
37Extends L<"Constructors" in Mail::Box::Message|Mail::Box::Message/"Constructors">.
38
39=over 4
40
41=item $obj-E<gt>B<clone>(%options)
42
43Inherited, see L<Mail::Message/"Constructors">
44
45=item Mail::Box::Net::Message-E<gt>B<new>(%options)
46
47 -Option    --Defined in        --Default
48  body        Mail::Message       undef
49  body_type   Mail::Box::Message  <from folder>
50  deleted     Mail::Message       <false>
51  field_type  Mail::Message       undef
52  folder      Mail::Box::Message  <required>
53  head        Mail::Message       undef
54  head_type   Mail::Message       Mail::Message::Head::Complete
55  labels      Mail::Message       {}
56  log         Mail::Reporter      'WARNINGS'
57  messageId   Mail::Message       undef
58  modified    Mail::Message       <false>
59  size        Mail::Box::Message  undef
60  trace       Mail::Reporter      'WARNINGS'
61  trusted     Mail::Message       <false>
62  unique                          <unique string>
63
64=over 2
65
66=item body => OBJECT
67
68=item body_type => CODE|CLASS
69
70=item deleted => BOOLEAN
71
72=item field_type => CLASS
73
74=item folder => FOLDER
75
76=item head => OBJECT
77
78=item head_type => CLASS
79
80=item labels => ARRAY|HASH
81
82=item log => LEVEL
83
84=item messageId => STRING
85
86=item modified => BOOLEAN
87
88=item size => INTEGER
89
90=item trace => LEVEL
91
92=item trusted => BOOLEAN
93
94=item unique => STRING
95
96The unique keys which identifies this message on the remote server.
97
98=back
99
100=back
101
102=head2 Constructing a message
103
104Extends L<"Constructing a message" in Mail::Box::Message|Mail::Box::Message/"Constructing a message">.
105
106=over 4
107
108=item $obj-E<gt>B<bounce>( [<$rg_object|%options>] )
109
110Inherited, see L<Mail::Message::Construct::Bounce/"Constructing a message">
111
112=item Mail::Box::Net::Message-E<gt>B<build>( [$message|$part|$body], $content )
113
114Inherited, see L<Mail::Message::Construct::Build/"Constructing a message">
115
116=item Mail::Box::Net::Message-E<gt>B<buildFromBody>($body, [$head], $headers)
117
118Inherited, see L<Mail::Message::Construct::Build/"Constructing a message">
119
120=item $obj-E<gt>B<forward>(%options)
121
122Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
123
124=item $obj-E<gt>B<forwardAttach>(%options)
125
126Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
127
128=item $obj-E<gt>B<forwardEncapsulate>(%options)
129
130Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
131
132=item $obj-E<gt>B<forwardInline>(%options)
133
134Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
135
136=item $obj-E<gt>B<forwardNo>(%options)
137
138Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
139
140=item $obj-E<gt>B<forwardPostlude>()
141
142Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
143
144=item $obj-E<gt>B<forwardPrelude>()
145
146Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
147
148=item $obj-E<gt>B<forwardSubject>(STRING)
149
150Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message">
151
152=item Mail::Box::Net::Message-E<gt>B<read>($fh|STRING|SCALAR|ARRAY, %options)
153
154Inherited, see L<Mail::Message::Construct::Read/"Constructing a message">
155
156=item $obj-E<gt>B<rebuild>(%options)
157
158Inherited, see L<Mail::Message::Construct::Rebuild/"Constructing a message">
159
160=item $obj-E<gt>B<reply>(%options)
161
162Inherited, see L<Mail::Message::Construct::Reply/"Constructing a message">
163
164=item $obj-E<gt>B<replyPrelude>( [STRING|$field|$address|ARRAY-$of-$things] )
165
166Inherited, see L<Mail::Message::Construct::Reply/"Constructing a message">
167
168=item $obj-E<gt>B<replySubject>(STRING)
169
170=item Mail::Box::Net::Message-E<gt>B<replySubject>(STRING)
171
172Inherited, see L<Mail::Message::Construct::Reply/"Constructing a message">
173
174=back
175
176=head2 The message
177
178Extends L<"The message" in Mail::Box::Message|Mail::Box::Message/"The message">.
179
180=over 4
181
182=item $obj-E<gt>B<container>()
183
184Inherited, see L<Mail::Message/"The message">
185
186=item $obj-E<gt>B<copyTo>($folder, %options)
187
188Inherited, see L<Mail::Box::Message/"The message">
189
190=item $obj-E<gt>B<folder>( [$folder] )
191
192Inherited, see L<Mail::Box::Message/"The message">
193
194=item $obj-E<gt>B<isDummy>()
195
196Inherited, see L<Mail::Message/"The message">
197
198=item $obj-E<gt>B<isPart>()
199
200Inherited, see L<Mail::Message/"The message">
201
202=item $obj-E<gt>B<messageId>()
203
204Inherited, see L<Mail::Message/"The message">
205
206=item $obj-E<gt>B<moveTo>($folder, %options)
207
208Inherited, see L<Mail::Box::Message/"The message">
209
210=item $obj-E<gt>B<partNumber>()
211
212Inherited, see L<Mail::Message/"The message">
213
214=item $obj-E<gt>B<print>( [$fh] )
215
216Inherited, see L<Mail::Message/"The message">
217
218=item $obj-E<gt>B<send>( [$mailer], %options )
219
220Inherited, see L<Mail::Message/"The message">
221
222=item $obj-E<gt>B<seqnr>( [$integer] )
223
224Inherited, see L<Mail::Box::Message/"The message">
225
226=item $obj-E<gt>B<size>()
227
228Inherited, see L<Mail::Message/"The message">
229
230=item $obj-E<gt>B<toplevel>()
231
232Inherited, see L<Mail::Message/"The message">
233
234=item $obj-E<gt>B<unique>( [STRING|undef] )
235
236Returns the name of the file in which this message is actually stored.  This
237will return C<undef> when the message is not stored in a file.  When a STRING
238is specified, a new identifier is stored first.
239
240=item $obj-E<gt>B<write>( [$fh] )
241
242Inherited, see L<Mail::Message/"The message">
243
244=back
245
246=head2 The header
247
248Extends L<"The header" in Mail::Box::Message|Mail::Box::Message/"The header">.
249
250=over 4
251
252=item $obj-E<gt>B<bcc>()
253
254Inherited, see L<Mail::Message/"The header">
255
256=item $obj-E<gt>B<cc>()
257
258Inherited, see L<Mail::Message/"The header">
259
260=item $obj-E<gt>B<date>()
261
262Inherited, see L<Mail::Message/"The header">
263
264=item $obj-E<gt>B<destinations>()
265
266Inherited, see L<Mail::Message/"The header">
267
268=item $obj-E<gt>B<from>()
269
270Inherited, see L<Mail::Message/"The header">
271
272=item $obj-E<gt>B<get>($fieldname)
273
274Inherited, see L<Mail::Message/"The header">
275
276=item $obj-E<gt>B<guessTimestamp>()
277
278Inherited, see L<Mail::Message/"The header">
279
280=item $obj-E<gt>B<head>( [$head] )
281
282Inherited, see L<Mail::Message/"The header">
283
284=item $obj-E<gt>B<nrLines>()
285
286Inherited, see L<Mail::Message/"The header">
287
288=item $obj-E<gt>B<sender>()
289
290Inherited, see L<Mail::Message/"The header">
291
292=item $obj-E<gt>B<study>($fieldname)
293
294Inherited, see L<Mail::Message/"The header">
295
296=item $obj-E<gt>B<subject>()
297
298Inherited, see L<Mail::Message/"The header">
299
300=item $obj-E<gt>B<timestamp>()
301
302Inherited, see L<Mail::Message/"The header">
303
304=item $obj-E<gt>B<to>()
305
306Inherited, see L<Mail::Message/"The header">
307
308=back
309
310=head2 The body
311
312Extends L<"The body" in Mail::Box::Message|Mail::Box::Message/"The body">.
313
314=over 4
315
316=item $obj-E<gt>B<body>( [$body] )
317
318Inherited, see L<Mail::Message/"The body">
319
320=item $obj-E<gt>B<contentType>()
321
322Inherited, see L<Mail::Message/"The body">
323
324=item $obj-E<gt>B<decoded>(%options)
325
326Inherited, see L<Mail::Message/"The body">
327
328=item $obj-E<gt>B<encode>(%options)
329
330Inherited, see L<Mail::Message/"The body">
331
332=item $obj-E<gt>B<isMultipart>()
333
334Inherited, see L<Mail::Message/"The body">
335
336=item $obj-E<gt>B<isNested>()
337
338Inherited, see L<Mail::Message/"The body">
339
340=item $obj-E<gt>B<parts>( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
341
342Inherited, see L<Mail::Message/"The body">
343
344=back
345
346=head2 Flags
347
348Extends L<"Flags" in Mail::Box::Message|Mail::Box::Message/"Flags">.
349
350=over 4
351
352=item $obj-E<gt>B<delete>()
353
354Inherited, see L<Mail::Message/"Flags">
355
356=item $obj-E<gt>B<deleted>( [BOOLEAN] )
357
358Inherited, see L<Mail::Message/"Flags">
359
360=item $obj-E<gt>B<isDeleted>()
361
362Inherited, see L<Mail::Message/"Flags">
363
364=item $obj-E<gt>B<isModified>()
365
366Inherited, see L<Mail::Message/"Flags">
367
368=item $obj-E<gt>B<label>($label|PAIRS)
369
370Inherited, see L<Mail::Message/"Flags">
371
372=item $obj-E<gt>B<labels>()
373
374Inherited, see L<Mail::Message/"Flags">
375
376=item $obj-E<gt>B<labelsToStatus>()
377
378Inherited, see L<Mail::Message/"Flags">
379
380=item $obj-E<gt>B<modified>( [BOOLEAN] )
381
382Inherited, see L<Mail::Message/"Flags">
383
384=item $obj-E<gt>B<statusToLabels>()
385
386Inherited, see L<Mail::Message/"Flags">
387
388=back
389
390=head2 The whole message as text
391
392Extends L<"The whole message as text" in Mail::Box::Message|Mail::Box::Message/"The whole message as text">.
393
394=over 4
395
396=item $obj-E<gt>B<file>()
397
398Inherited, see L<Mail::Message::Construct::Text/"The whole message as text">
399
400=item $obj-E<gt>B<lines>()
401
402Inherited, see L<Mail::Message::Construct::Text/"The whole message as text">
403
404=item $obj-E<gt>B<printStructure>( [$fh|undef],[$indent] )
405
406Inherited, see L<Mail::Message::Construct::Text/"The whole message as text">
407
408=item $obj-E<gt>B<string>()
409
410Inherited, see L<Mail::Message::Construct::Text/"The whole message as text">
411
412=back
413
414=head2 Internals
415
416Extends L<"Internals" in Mail::Box::Message|Mail::Box::Message/"Internals">.
417
418=over 4
419
420=item $obj-E<gt>B<clonedFrom>()
421
422Inherited, see L<Mail::Message/"Internals">
423
424=item Mail::Box::Net::Message-E<gt>B<coerce>($message, %options)
425
426Inherited, see L<Mail::Message/"Internals">
427
428=item $obj-E<gt>B<diskDelete>()
429
430Inherited, see L<Mail::Box::Message/"Internals">
431
432=item $obj-E<gt>B<isDelayed>()
433
434Inherited, see L<Mail::Message/"Internals">
435
436=item $obj-E<gt>B<loadBody>()
437
438=item $obj-E<gt>B<readBody>( $parser, $head, [$bodytype] )
439
440Inherited, see L<Mail::Box::Message/"Internals">
441
442=item $obj-E<gt>B<readFromParser>( $parser, [$bodytype] )
443
444Inherited, see L<Mail::Message/"Internals">
445
446=item $obj-E<gt>B<readHead>( $parser, [$class] )
447
448Inherited, see L<Mail::Message/"Internals">
449
450=item $obj-E<gt>B<recursiveRebuildPart>($part, %options)
451
452Inherited, see L<Mail::Message::Construct::Rebuild/"Internals">
453
454=item $obj-E<gt>B<storeBody>($body)
455
456Inherited, see L<Mail::Message/"Internals">
457
458=item $obj-E<gt>B<takeMessageId>( [STRING] )
459
460Inherited, see L<Mail::Message/"Internals">
461
462=back
463
464=head2 Error handling
465
466Extends L<"Error handling" in Mail::Box::Message|Mail::Box::Message/"Error handling">.
467
468=over 4
469
470=item $obj-E<gt>B<AUTOLOAD>()
471
472Inherited, see L<Mail::Message::Construct/"METHODS">
473
474=item $obj-E<gt>B<addReport>($object)
475
476Inherited, see L<Mail::Reporter/"Error handling">
477
478=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
479
480=item Mail::Box::Net::Message-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
481
482Inherited, see L<Mail::Reporter/"Error handling">
483
484=item $obj-E<gt>B<errors>()
485
486Inherited, see L<Mail::Reporter/"Error handling">
487
488=item $obj-E<gt>B<log>( [$level, [$strings]] )
489
490=item Mail::Box::Net::Message-E<gt>B<log>( [$level, [$strings]] )
491
492Inherited, see L<Mail::Reporter/"Error handling">
493
494=item $obj-E<gt>B<logPriority>($level)
495
496=item Mail::Box::Net::Message-E<gt>B<logPriority>($level)
497
498Inherited, see L<Mail::Reporter/"Error handling">
499
500=item $obj-E<gt>B<logSettings>()
501
502Inherited, see L<Mail::Reporter/"Error handling">
503
504=item $obj-E<gt>B<notImplemented>()
505
506Inherited, see L<Mail::Reporter/"Error handling">
507
508=item $obj-E<gt>B<report>( [$level] )
509
510Inherited, see L<Mail::Reporter/"Error handling">
511
512=item $obj-E<gt>B<reportAll>( [$level] )
513
514Inherited, see L<Mail::Reporter/"Error handling">
515
516=item $obj-E<gt>B<shortSize>( [$value] )
517
518=item Mail::Box::Net::Message-E<gt>B<shortSize>( [$value] )
519
520Inherited, see L<Mail::Message/"Error handling">
521
522=item $obj-E<gt>B<shortString>()
523
524Inherited, see L<Mail::Message/"Error handling">
525
526=item $obj-E<gt>B<trace>( [$level] )
527
528Inherited, see L<Mail::Reporter/"Error handling">
529
530=item $obj-E<gt>B<warnings>()
531
532Inherited, see L<Mail::Reporter/"Error handling">
533
534=back
535
536=head2 Cleanup
537
538Extends L<"Cleanup" in Mail::Box::Message|Mail::Box::Message/"Cleanup">.
539
540=over 4
541
542=item $obj-E<gt>B<DESTROY>()
543
544Inherited, see L<Mail::Reporter/"Cleanup">
545
546=item $obj-E<gt>B<destruct>()
547
548Inherited, see L<Mail::Box::Message/"Cleanup">
549
550=back
551
552=head1 DETAILS
553
554Extends L<"DETAILS" in Mail::Box::Message|Mail::Box::Message/"DETAILS">.
555
556=head1 DIAGNOSTICS
557
558=over 4
559
560=item Error: Cannot coerce a $class object into a $class object
561
562=item Error: Cannot include forward source as $include.
563
564Unknown alternative for the L<forward(include)|Mail::Message::Construct::Forward/"Constructing a message">.  Valid choices are
565C<NO>, C<INLINE>, C<ATTACH>, and C<ENCAPSULATE>.
566
567=item Error: Cannot include reply source as $include.
568
569Unknown alternative for the C<include> option of L<reply()|Mail::Message::Construct::Reply/"Constructing a message">.  Valid
570choices are C<NO>, C<INLINE>, and C<ATTACH>.
571
572=item Error: Method bounce requires To, Cc, or Bcc
573
574The message L<bounce()|Mail::Message::Construct::Bounce/"Constructing a message"> method forwards a received message off to someone
575else without modification; you must specified it's new destination.
576If you have the urge not to specify any destination, you probably
577are looking for L<reply()|Mail::Message::Construct::Reply/"Constructing a message">. When you wish to modify the content, use
578L<forward()|Mail::Message::Construct::Forward/"Constructing a message">.
579
580=item Error: Method forwardAttach requires a preamble
581
582=item Error: Method forwardEncapsulate requires a preamble
583
584=item Error: No address to create forwarded to.
585
586If a forward message is created, a destination address must be specified.
587
588=item Error: No default mailer found to send message.
589
590The message L<send()|Mail::Message/"The message"> mechanism had not enough information to automatically
591find a mail transfer agent to sent this message.  Specify a mailer
592explicitly using the C<via> options.
593
594=item Error: No rebuild rule $name defined.
595
596=item Error: Only build() Mail::Message's; they are not in a folder yet
597
598You may wish to construct a message to be stored in a some kind
599of folder, but you need to do that in two steps.  First, create a
600normal L<Mail::Message|Mail::Message>, and then add it to the folder.  During this
601L<Mail::Box::addMessage()|Mail::Box/"The folder"> process, the message will get L<coerce()|Mail::Message/"Internals">-d
602into the right message type, adding storage information and the like.
603
604=item Error: Package $package does not implement $method.
605
606Fatal error: the specific package (or one of its superclasses) does not
607implement this method where it should. This message means that some other
608related classes do implement this method however the class at hand does
609not.  Probably you should investigate this and probably inform the author
610of the package.
611
612=item Error: Unable to read delayed body.
613
614=item Error: Unable to read delayed head.
615
616=item Error: coercion starts with some object
617
618=back
619
620=head1 SEE ALSO
621
622This module is part of Mail-Box distribution version 3.009,
623built on August 18, 2020. Website: F<http://perl.overmeer.net/CPAN/>
624
625=head1 LICENSE
626
627Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see ChangeLog.
628
629This program is free software; you can redistribute it and/or modify it
630under the same terms as Perl itself.
631See F<http://dev.perl.org/licenses/>
632
633