1=encoding utf8
2
3=head1 NAME
4
5Mail::Message::Head::ResentGroup - header fields tracking message delivery
6
7=head1 INHERITANCE
8
9 Mail::Message::Head::ResentGroup
10   is a Mail::Message::Head::FieldGroup
11   is a Mail::Reporter
12
13=head1 SYNOPSIS
14
15 use Mail::Message::Head::ResentGroup;
16 my $rg = Mail::Message::Head::ResentGroup->new(head => $head,
17              From => 'me@home.nl', To => 'You@tux.aq');
18 $head->addResentGroup($rg);
19
20 my $rg = $head->addResentGroup(From => 'me');
21
22 my @from = $rg->From;
23
24 my @rgs = $head->resentGroups;
25 $rg[2]->delete if @rgs > 2;
26
27=head1 DESCRIPTION
28
29A I<resent group> is a set of header fields which describe one intermediate
30step in the message transport.  Resent groups B<have NOTHING to do> with
31user activety; there is no relation to the C<user's> sense of creating
32reply, forward, or bounce messages at all!
33
34Extends L<"DESCRIPTION" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"DESCRIPTION">.
35
36=head1 METHODS
37
38Extends L<"METHODS" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"METHODS">.
39
40=head2 Constructors
41
42Extends L<"Constructors" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Constructors">.
43
44=over 4
45
46=item $obj-E<gt>B<clone>()
47
48Inherited, see L<Mail::Message::Head::FieldGroup/"Constructors">
49
50=item $obj-E<gt>B<from>( [<$head|$message>, %options] )
51
52WARNING: this method has two very different purposes.  For backward
53compatibility reasons, without arguments L<resentFrom()|Mail::Message::Head::ResentGroup/"Access to the header"> is called to
54return the C<From> field of this resent group.
55
56With any arguments, a list of C<Mail::Message::Head::ResentGroup> objects
57is returned, taken from the specified $message or message $head.
58
59=item $obj-E<gt>B<implementedTypes>()
60
61=item Mail::Message::Head::ResentGroup-E<gt>B<implementedTypes>()
62
63Inherited, see L<Mail::Message::Head::FieldGroup/"Constructors">
64
65=item Mail::Message::Head::ResentGroup-E<gt>B<new>( [$fields], %options )
66
67Create an object which maintains one set of resent headers.  The
68$fields are L<Mail::Message::Field|Mail::Message::Field> objects from the same header.
69
70%options which start with capitals will be used to construct additional
71fields.  These option names are prepended with C<Resent-*>, keeping the
72capitization of what is specified.
73
74 -Option      --Defined in                     --Default
75  Bcc                                            undef
76  Cc                                             undef
77  Date                                           <now>
78  Delivered-To                                   undef
79  From                                           <required>
80  Message-ID                                     <uniquely created>
81  Received                                       <created>
82  Return-Path                                    undef
83  Sender                                         undef
84  To                                             undef
85  head                                           <created automatically>
86  log           Mail::Reporter                   'WARNINGS'
87  message_head                                   undef
88  software      Mail::Message::Head::FieldGroup  undef
89  trace         Mail::Reporter                   'WARNINGS'
90  type          Mail::Message::Head::FieldGroup  undef
91  version       Mail::Message::Head::FieldGroup  undef
92
93=over 2
94
95=item Bcc => STRING|OBJECT|OBJECTS
96
97=item Cc => STRING|OBJECT|OBJECTS
98
99=item Date => STRING
100
101When this resent-group is dispatched by the resender of the message. Like
102the C<Date> field, it is not the date and time that the message was
103actually transported.
104
105=item Delivered-To => STRING|FIELD
106
107=item From => STRING|OBJECT|OBJECTS
108
109=item Message-ID => STRING|FIELD
110
111The C<Resent-Message-ID> which identifies this resent group.  The FIELD
112must contain a message id.
113
114=item Received => STRING
115
116The C<Received> field is the starting line for a resent group of header
117lines. If it is not defined, one is created using L<createReceived()|Mail::Message::Head::ResentGroup/"Internals">.
118
119=item Return-Path => STRING|FIELD
120
121=item Sender => STRING|OBJECT
122
123Only permitted when more than one from address is specified.  In this case,
124it selects one of these addresses as the main originator of the message.
125
126=item To => STRING|OBJECT|OBJECTS
127
128=item head => OBJECT
129
130The header where the data is stored in. By default a
131L<Mail::Message::Head::Partial|Mail::Message::Head::Partial> is created for you.
132
133=item log => LEVEL
134
135=item message_head => HEAD
136
137The real header of the message where this resent group is part of.  The
138C<head> used in this class is only a container for a subset of fields.
139
140=item software => STRING
141
142=item trace => LEVEL
143
144=item type => STRING
145
146=item version => STRING
147
148=back
149
150=back
151
152=head2 The header
153
154Extends L<"The header" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"The header">.
155
156=over 4
157
158=item $obj-E<gt>B<add>( <$field, $value> | $object )
159
160All fields appear only once, so C<add()> behaves as L<set()|Mail::Message::Head::ResentGroup/"The header">.
161
162=item $obj-E<gt>B<addFields>( [$fieldnames] )
163
164Not applicable to resent-groups: the same name can appear in more than
165one group.  Therefore, a FIELDNAME is sufficiently distinctive.
166
167=item $obj-E<gt>B<attach>($head)
168
169Inherited, see L<Mail::Message::Head::FieldGroup/"The header">
170
171=item $obj-E<gt>B<delete>()
172
173Inherited, see L<Mail::Message::Head::FieldGroup/"The header">
174
175=item $obj-E<gt>B<fieldNames>()
176
177Inherited, see L<Mail::Message::Head::FieldGroup/"The header">
178
179=item $obj-E<gt>B<fields>()
180
181Inherited, see L<Mail::Message::Head::FieldGroup/"The header">
182
183=item $obj-E<gt>B<head>()
184
185Inherited, see L<Mail::Message::Head::FieldGroup/"The header">
186
187=item $obj-E<gt>B<messageHead>( [$head] )
188
189Returns (optionally after setting) the real header where this resent group
190belongs to.  This may be undef at creation, and then later filled in
191when L<Mail::Message::Head::Complete::addResentGroup()|Mail::Message::Head::Complete/"Access to the header"> is called.
192
193=item $obj-E<gt>B<orderedFields>()
194
195Returns the fields in the order as should appear in header according
196to rfc2822.  For the C<Resent-*> fields of the group, the order is
197not that important, but the C<Return-Path>, C<Delivered-To>, and C<Received>
198must come first.  Only fields mentioned in the RFC are returned.
199
200=item $obj-E<gt>B<set>( <$field, $value> | $object )
201
202Set a $field to a (new) $value.  The $field names which do not start with
203'Resent-*' but need it will have that added.  It is also an option to
204specify a fully prepared message field $object.  In any case, a field
205$object is returned.
206
207example:
208
209 my $this = Mail::Message::Head::ResentGroup->new;
210 $this->set(To => 'fish@tux.aq');
211 $msg->addResentGroup($this);
212 $msg->send;
213
214 $msg->bounce(To => 'fish@tux.aq')->send;   # the same
215
216 my $this = Mail::Message::Head::ResentGroup
217     ->new(To => 'fish@tux.aq');
218
219=back
220
221=head2 Access to the header
222
223Extends L<"Access to the header" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Access to the header">.
224
225=over 4
226
227=item $obj-E<gt>B<bcc>()
228
229In scalar context, the C<Resent-Bcc> field is returned.  In list context,
230the addresses as specified within the bcc field are returned as
231L<Mail::Address|Mail::Address> objects.  Bcc fields are not transmitted (hidden for
232external parties).
233
234=item $obj-E<gt>B<cc>()
235
236In scalar context, the C<Resent-Cc> field is returned.  In list context,
237the addresses as specified within the cc field are returned as
238L<Mail::Address|Mail::Address> objects.
239
240=item $obj-E<gt>B<date>()
241
242Returns the C<Resent-Date> field, or C<undef> if it was not defined.
243
244=item $obj-E<gt>B<dateTimestamp>()
245
246The timestamp as stored within the C<Resent-Date> field converted to
247local system time.
248
249=item $obj-E<gt>B<deliveredTo>()
250
251The field which describes the C<Delivered-To> of this resent group.
252
253=item $obj-E<gt>B<destinations>()
254
255Returns a list of all addresses specified in the C<Resent-To>, C<-Cc>, and
256C<-Bcc> fields of this resent group.
257
258=item $obj-E<gt>B<isResentGroupFieldName>($name)
259
260=item Mail::Message::Head::ResentGroup-E<gt>B<isResentGroupFieldName>($name)
261
262=item $obj-E<gt>B<messageId>()
263
264Returns the message-ID used for this group of resent lines.
265
266=item $obj-E<gt>B<received>()
267
268The field which describes the C<Received> data of this resent group.
269
270=item $obj-E<gt>B<receivedTimestamp>()
271
272The timestamp as stored within the C<Received> field converted to
273local system time.
274
275=item $obj-E<gt>B<resentFrom>()
276
277In scalar context, the C<Resent-From> field is returned.  In list
278context, the addresses as specified within the from field are
279returned as L<Mail::Address|Mail::Address> objects.
280
281For reasons of backward compatibility and consistency, the L<from()|Mail::Message::Head::ResentGroup/"METHODS">
282method will return the same as this method.
283
284=item $obj-E<gt>B<returnPath>()
285
286The field which describes the C<Return-Path> of this resent group.
287
288=item $obj-E<gt>B<sender>()
289
290In scalar context, the C<Resent-Sender> field is returned.  In list
291context, the addresses as specified within the from field are
292returned as L<Mail::Address|Mail::Address> objects.
293
294=item $obj-E<gt>B<software>()
295
296Inherited, see L<Mail::Message::Head::FieldGroup/"Access to the header">
297
298=item $obj-E<gt>B<to>()
299
300In scalar context, the C<Resent-To> field is returned.  In list context,
301the addresses as specified within the to field are returned as
302L<Mail::Address|Mail::Address> objects.
303
304=item $obj-E<gt>B<type>()
305
306Inherited, see L<Mail::Message::Head::FieldGroup/"Access to the header">
307
308=item $obj-E<gt>B<version>()
309
310Inherited, see L<Mail::Message::Head::FieldGroup/"Access to the header">
311
312=back
313
314=head2 Internals
315
316Extends L<"Internals" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Internals">.
317
318=over 4
319
320=item $obj-E<gt>B<collectFields>( [$name] )
321
322Inherited, see L<Mail::Message::Head::FieldGroup/"Internals">
323
324=item $obj-E<gt>B<createReceived>( [$domain] )
325
326Create a received field for this resent group.  This is automatically
327called if none was specified during creation of this resent group object.
328
329The content of this field is described in RFC2821 section 4.4.  It could use
330some improvement.
331
332=item $obj-E<gt>B<detected>($type, $software, $version)
333
334Inherited, see L<Mail::Message::Head::FieldGroup/"Internals">
335
336=back
337
338=head2 Error handling
339
340Extends L<"Error handling" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Error handling">.
341
342=over 4
343
344=item $obj-E<gt>B<AUTOLOAD>()
345
346Inherited, see L<Mail::Reporter/"Error handling">
347
348=item $obj-E<gt>B<addReport>($object)
349
350Inherited, see L<Mail::Reporter/"Error handling">
351
352=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
353
354=item Mail::Message::Head::ResentGroup-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
355
356Inherited, see L<Mail::Reporter/"Error handling">
357
358=item $obj-E<gt>B<details>()
359
360Inherited, see L<Mail::Message::Head::FieldGroup/"Error handling">
361
362=item $obj-E<gt>B<errors>()
363
364Inherited, see L<Mail::Reporter/"Error handling">
365
366=item $obj-E<gt>B<log>( [$level, [$strings]] )
367
368=item Mail::Message::Head::ResentGroup-E<gt>B<log>( [$level, [$strings]] )
369
370Inherited, see L<Mail::Reporter/"Error handling">
371
372=item $obj-E<gt>B<logPriority>($level)
373
374=item Mail::Message::Head::ResentGroup-E<gt>B<logPriority>($level)
375
376Inherited, see L<Mail::Reporter/"Error handling">
377
378=item $obj-E<gt>B<logSettings>()
379
380Inherited, see L<Mail::Reporter/"Error handling">
381
382=item $obj-E<gt>B<notImplemented>()
383
384Inherited, see L<Mail::Reporter/"Error handling">
385
386=item $obj-E<gt>B<print>( [$fh] )
387
388Inherited, see L<Mail::Message::Head::FieldGroup/"Error handling">
389
390=item $obj-E<gt>B<report>( [$level] )
391
392Inherited, see L<Mail::Reporter/"Error handling">
393
394=item $obj-E<gt>B<reportAll>( [$level] )
395
396Inherited, see L<Mail::Reporter/"Error handling">
397
398=item $obj-E<gt>B<trace>( [$level] )
399
400Inherited, see L<Mail::Reporter/"Error handling">
401
402=item $obj-E<gt>B<warnings>()
403
404Inherited, see L<Mail::Reporter/"Error handling">
405
406=back
407
408=head2 Cleanup
409
410Extends L<"Cleanup" in Mail::Message::Head::FieldGroup|Mail::Message::Head::FieldGroup/"Cleanup">.
411
412=over 4
413
414=item $obj-E<gt>B<DESTROY>()
415
416Inherited, see L<Mail::Reporter/"Cleanup">
417
418=back
419
420=head1 DIAGNOSTICS
421
422=over 4
423
424=item Error: Message header required for creation of ResentGroup.
425
426It is required to know to which header the resent-group
427is created.  Use the C<head> option.  Maybe you should use
428L<Mail::Message::Head::Complete::addResentGroup()|Mail::Message::Head::Complete/"Access to the header"> with DATA, which will
429organize the correct initiations for you.
430
431=item Error: Package $package does not implement $method.
432
433Fatal error: the specific package (or one of its superclasses) does not
434implement this method where it should. This message means that some other
435related classes do implement this method however the class at hand does
436not.  Probably you should investigate this and probably inform the author
437of the package.
438
439=back
440
441=head1 SEE ALSO
442
443This module is part of Mail-Message distribution version 3.011,
444built on July 27, 2021. Website: F<http://perl.overmeer.net/CPAN/>
445
446=head1 LICENSE
447
448Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
449
450This program is free software; you can redistribute it and/or modify it
451under the same terms as Perl itself.
452See F<http://dev.perl.org/licenses/>
453
454