1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
|
=head1 NAME
Mail::Message::Construct::Build - building a Mail::Message from components
=head1 SYNOPSIS
my $msg3 = Mail::Message->build
(From => 'me', data => "only two\nlines\n");
my $msg4 = Mail::Message->buildFromBody($body);
=head1 DESCRIPTION
Complex functionality on L<Mail::Message|Mail::Message> objects is implemented in
different files which are autoloaded. This file implements the
functionality related to building of messages from various components.
=head1 METHODS
=head2 Constructing a message
Mail::Message-E<gt>B<build>([MESSAGE|PART|BODY], CONTENT)
=over 4
Simplified message object builder. In case a MESSAGE or message PART is
specified, a new message is created with the same body to start with, but
new headers. A BODY may be specified as well. However, there are more
ways to add data simply.
The CONTENT is a list of key-value pairs and header field objects.
The keys which start with a capital are used as header-lines. Lower-cased
fields are used for other purposes as listed below. Each field may be used
more than once. Pairs where the value is C<undef> are ignored.
If more than one C<data>, C<file>, and C<attach> is specified,
a multi-parted message is created. Some C<Content-> fields are
treated separately: to enforce the content lines of the produced
message body B<after> it has been created. For instance, to explicitly
state that you wish a C<multipart/alternative> in stead of the default
C<multipart/mixed>. If you wish to specify the type per datum, you need
to start playing with L<Mail::Message::Body|Mail::Message::Body> objects yourself.
This C<build> method will use L<buildFromBody()|Mail::Message::Construct::Build/"Constructing a message"> when the body object has
been constructed. Together, they produce your message.
Option--Defined in --Default
attach undef
data undef
file undef
files [ ]
head undef
. attach BODY|PART|MESSAGE|ARRAY
=over 4
One attachment to the message. Each attachment can be full MESSAGE, a
PART, or a BODY.
Any MESSAGE will get encapsulated into a C<message/rfc822> body.
You can specify many items (may be of different types) at once.
attach => $folder->message(3)->decoded # body
attach => $folder->message(3) # message
attach => [ $msg1, $msg2->part(6), $msg3->body ];
=back
. data STRING|ARRAY-OF-LINES
=over 4
The text for one part, specified as one STRING, or an ARRAY of lines. Each
line, including the last, must be terminated by a newline. This argument
is passed to L<Mail::Message::Body::new(data)|Mail::Message::Body/"Constructors"> to
construct one.
data => [ "line 1\n", "line 2\n" ] # array of lines
data => <<'TEXT' # string
line 1
line 2
TEXT
=back
. file FILENAME|FILEHANDLE|IOHANDLE
=over 4
Create a body where the data is read from the specified FILENAME,
FILEHANDLE, or object of type IO::Handle. Also this body is used
to create a L<Mail::Message::Body|Mail::Message::Body>.
my $in = IO::File->new('/etc/passwd', 'r');
file => 'picture.jpg' # filename
file => \*MYINPUTFILE # file handle
file => $in # any IO::Handle
open my $in, '<', '/etc/passwd'; # alternative for IO::File
=back
. files ARRAY-OF-FILE
=over 4
See option file, but then an array reference collection more of them.
=back
. head HEAD
=over 4
Start with a prepared header, otherwise one is created.
=back
I<Example:>
my $msg = Mail::Message->build
( From => 'me@home.nl'
, To => Mail::Address->new('your name', 'you@yourplace.aq')
, Cc => 'everyone@example.com'
, $other_message->get('Bcc')
, data => [ "This is\n", "the first part of\n", "the message\n" ]
, file => 'myself.gif'
, file => 'you.jpg'
, attach => $signature
);
my $msg = Mail::Message->build
( To => 'you'
, 'Content-Type' => 'text/html'
, data => "<html></html>"
);
=back
Mail::Message-E<gt>B<buildFromBody>(BODY, [HEAD], HEADERS)
=over 4
Shape a message around a BODY. Bodies have information about their
content in them, which is used to construct a header for the message.
You may specify a HEAD object which is pre-initialized, or one is
created for you (also when HEAD is C<undef>).
Next to that, more HEADERS can be specified which are stored in that
header.
Header fields are added in order, and before the header lines as
defined by the body are taken. They may be supplied as key-value
pairs or L<Mail::Message::Field|Mail::Message::Field> objects. In case of a key-value
pair, the field's name is to be used as key and the value is a
string, address (Mail::Address object), or array of addresses.
A C<Date>, C<Message-Id>, and C<MIME-Version> field are added unless
supplied.
I<Example:>
my $type = Mail::Message::Field->new('Content-Type', 'text/html'
, 'charset="us-ascii"');
my @to = ( Mail::Address->new('Your name', 'you@example.com')
, 'world@example.info'
);
my $msg = Mail::Message->buildFromBody
( $body
, From => 'me@example.nl'
, To => \@to
, $type
);
=back
=head1 DIAGNOSTICS
I<Error:> Only build() Mail::Message's; they are not in a folder yet
You may wish to construct a message to be stored in a some kind
of folder, but you need to do that in two steps. First, create a
normal L<Mail::Message|Mail::Message>, and then add it to the folder. During this
L<Mail::Box::addMessage()|Mail::Box/"The folder"> process, the message will get L<coerce()|Mail::Message/"Internals">-d
into the right message type, adding storage information and the like.
=head1 DETAILS
=head2 Building a message
=head3 Rapid building
Most messages you need to construct are relatively simple. Therefore,
this module provides a method to prepare a message with only one method
call: L<build()|Mail::Message::Construct::Build/"Constructing a message">.
=head3 Compared to MIME::Entity::build()
The C<build> method in MailBox is modelled after the C<build> method
as provided by MIMETools, but with a few simplifications:
=over 4
=item When a keys starts with a capital, than it is always a header field
=item When a keys is lower-cased, it is always something else
=item You use the real field-names, not abbreviations
=item All field names are accepted
=item You may specify field objects between key-value pairs
=item A lot of facts are auto-detected, like content-type and encoding
=item You can create a multipart at once
=back
Hum, reading the list above... what is equivalent? L<MIME::Entity> is
not that simple after all! Let's look at an example from MIME::Entity's
manual page:
### Create the top-level, and set up the mail headers:
$top = MIME::Entity->build(Type => "multipart/mixed",
From => 'me@myhost.com',
To => 'you@yourhost.com',
Subject => "Hello, nurse!");
### Attachment #1: a simple text document:
$top->attach(Path=>"./testin/short.txt");
### Attachment #2: a GIF file:
$top->attach(Path => "./docs/mime-sm.gif",
Type => "image/gif",
Encoding => "base64");
### Attachment #3: text we'll create with text we have on-hand:
$top->attach(Data => $contents);
The MailBox equivalent could be
my $msg = Mail::Message->build
( From => 'me@myhost.com'
, To => 'you@yourhost.com'
, Subject => "Hello, nurse!"
, file => "./testin/short.txt"
, file => "./docs/mime-sm.gif"
, data => $contents
);
One of the simplifications is that L<MIME::Types|MIME::Types> is used to lookup
the right content type and optimal transfer encoding. Good values
for content-disposition and such are added as well.
=head3 build, starting with nothing
See L<build()|Mail::Message::Construct::Build/"Constructing a message">.
=head3 buildFromBody, body becomes message
See L<buildFromBody()|Mail::Message::Construct::Build/"Constructing a message">.
=head3 The Content-* fields
The various C<Content-*> fields are not as harmless as they look. For
instance, the "Content-Type" field will have an effect on the default
transfer encoding.
When a message is built this way:
my $msg = Mail::Message->build
( 'Content-Type' => 'video/mpeg3'
, 'Content-Transfer-Encoding' => 'base64'
, 'Content-Disposition' => 'attachment'
, file => '/etc/passwd'
);
then first a C<text/plain> body is constructed (MIME::Types does not
find an extension on the filename so defaults to C<text/plain>), with
no encoding. Only when that body is ready, the new type and requested
encodings are set. The content of the body will get base64 encoded,
because it is requested that way.
What basically happens is this:
my $head = ...other header lines...;
my $body = Mail::Message::Body::Lines->new(file => '/etc/passwd');
$body->type('video/mpeg3');
$body->transferEncoding('base64');
$body->diposition('attachment');
my $msg = Mail::Message->buildFromBody($body, $head);
A safer way to construct the message is:
my $body = Mail::Message::Body::Lines->new
( file => '/etc/passwd'
, mime_type => 'video/mpeg3'
, transfer_encoding => 'base64'
, disposition => 'attachment'
);
my $msg = Mail::Message->buildFromBody
( $body
, ...other header lines...
);
In the latter program, you will immediately start with a body of
the right type.
=head1 REFERENCES
See the MailBox website at L<http://perl.overmeer.net/mailbox/> for more details.
=head1 COPYRIGHTS
Distribution version 2.068.
Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for
other contributors.
Copyright (c) 2001-2006 by the author(s). All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
|
