1Mail::Message::ConstrucUts:e:rBuCiolndt(r3i)buted Perl DMoaciulm:e:nMteastsiaogne::Construct::Build(3)
2
3
4

NAME

6       Mail::Message::Construct::Build - building a Mail::Message from
7       components
8

SYNOPSIS

10        my $msg1 = Mail::Message->build
11          ( From => 'me', data => "only two\nlines\n");
12
13        my $msg2 = Mail::Message->buildFromBody($body);
14
15        Mail::Message->build
16          ( From     => 'me@myhost.com'
17          , To       => 'you@yourhost.com'
18          , Subject  => "Read our folder!"
19
20          , data     => \@lines
21          , file     => 'folder.pdf'
22          )->send(via => 'postfix');
23

DESCRIPTION

25       Complex functionality on Mail::Message objects is implemented in
26       different files which are autoloaded.  This file implements the
27       building of messages from various simpler components.
28

METHODS

30   Constructing a message
31       Mail::Message->build( [$message|$part|$body], $content )
32           Simplified message object builder.  In case a $message or message
33           $part is specified, a new message is created with the same body to
34           start with, but new headers.  A $body may be specified as well.
35           However, there are more ways to add data simply.
36
37           The $content is a list of key-value pairs and header field objects.
38           The keys which start with a capital are used as header-lines.
39           Lower-cased fields are used for other purposes as listed below.
40           Each field may be used more than once.  Pairs where the value is
41           "undef" are ignored.
42
43           If more than one "data", "file", and "attach" is specified, a
44           multi-parted message is created.  Some "Content-*" fields are
45           treated separately: to enforce the content lines of the produced
46           message body after it has been created.  For instance, to
47           explicitly state that you wish a "multipart/alternative" in stead
48           of the default "multipart/mixed".  If you wish to specify the type
49           per datum, you need to start playing with Mail::Message::Body
50           objects yourself.
51
52           This "build" method will use buildFromBody() when the body object
53           has been constructed.  Together, they produce your message.
54
55            -Option--Default
56             attach  undef
57             data    undef
58             file    undef
59             files   [ ]
60             head    undef
61
62           attach => BODY|PART|MESSAGE|ARRAY
63             One attachment to the message.  Each attachment can be full
64             $message, a $part, or a $body.  Any $message will get
65             encapsulated into a "message/rfc822" body.  You can specify many
66             items (may be of different types) at once.
67
68              attach => $folder->message(3)->decoded  # body
69              attach => $folder->message(3)           # message
70              attach => [ $msg1, $msg2->part(6), $msg3->body ];
71
72           data => STRING|ARRAY-OF-LINES
73             The text for one part, specified as one STRING, or an ARRAY of
74             lines.  Each line, including the last, must be terminated by a
75             newline.  This argument is passed to
76             Mail::Message::Body::new(data) to construct one.
77
78               data => [ "line 1\n", "line 2\n" ]     # array of lines
79               data => <<'TEXT'                       # string
80              line 1
81              line 2
82              TEXT
83
84           file => FILENAME|FILEHANDLE|IOHANDLE|ARRAY
85             Create a body where the data is read from the specified FILENAME,
86             FILEHANDLE, or object of type IO::Handle.  Also this body is used
87             to create a Mail::Message::Body. [2.119] You may even pass more
88             than one file at once: 'file' and 'files' option are equivalent.
89
90              my $in = IO::File->new('/etc/passwd', 'r');
91
92              file  => 'picture.jpg'                   # filename
93              file  => \*MYINPUTFILE                   # file handle
94              file  => $in                             # any IO::Handle
95              files => [ 'picture.jpg', \*MYINPUTFILE, $in ]
96
97              open my $in, '<:raw', '/etc/passwd';    # alternative for IO::File
98
99           files => ARRAY-OF-FILE
100             Alias for option "file".
101
102           head => HEAD
103             Start with a prepared header, otherwise one is created.
104
105           example:
106
107            my $msg = Mail::Message->build
108             ( From    => 'me@home.nl'
109             , To      => Mail::Address->new('your name', 'you@yourplace.aq')
110             , Cc      => 'everyone@example.com'
111             , Subject => "Let's talk",
112             , $other_message->get('Bcc')
113
114             , data   => [ "This is\n", "the first part of\n", "the message\n" ]
115             , file   => 'myself.gif'
116             , file   => 'you.jpg'
117             , attach => $signature
118             );
119
120            my $msg = Mail::Message->build
121             ( To     => 'you'
122             , 'Content-Type' => 'text/html'
123             , data   => "<html></html>"
124             );
125
126       Mail::Message->buildFromBody($body, [$head], $headers)
127           Shape a message around a $body.  Bodies have information about
128           their content in them, which is used to construct a header for the
129           message.  You may specify a $head object which is pre-initialized,
130           or one is created for you (also when $head is "undef").  Next to
131           that, more $headers can be specified which are stored in that
132           header.
133
134           Header fields are added in order, and before the header lines as
135           defined by the body are taken.  They may be supplied as key-value
136           pairs or Mail::Message::Field objects.  In case of a key-value
137           pair, the field's name is to be used as key and the value is a
138           string, address (Mail::Address object), or array of addresses.
139
140           A "Date", "Message-Id", and "MIME-Version" field are added unless
141           supplied.
142
143           example:
144
145            my $type = Mail::Message::Field->new('Content-Type', 'text/html'
146              , 'charset="us-ascii"');
147
148            my @to   = ( Mail::Address->new('Your name', 'you@example.com')
149                       , 'world@example.info'
150                       );
151
152            my $msg  = Mail::Message->buildFromBody
153              ( $body
154              , From => 'me@example.nl'
155              , To   => \@to
156              , $type
157              );
158

DETAILS

160   Building a message
161       Rapid building
162
163       Most messages you need to construct are relatively simple.  Therefore,
164       this module provides a method to prepare a message with only one method
165       call: build().
166
167       Compared to MIME::Entity::build()
168
169       The "build" method in MailBox is modelled after the "build" method as
170       provided by MIMETools, but with a few simplifications:
171
172       When a keys starts with a capital, than it is always a header field
173       When a keys is lower-cased, it is always something else
174       You use the real field-names, not abbreviations
175       All field names are accepted
176       You may specify field objects between key-value pairs
177       A lot of facts are auto-detected, like content-type and encoding
178       You can create a multipart at once
179
180       Hum, reading the list above... what is equivalent?  MIME::Entity is not
181       that simple after all!  Let's look at an example from MIME::Entity's
182       manual page:
183
184        ### Create the top-level, and set up the mail headers:
185        $top = MIME::Entity->build(Type     => "multipart/mixed",
186                                   From     => 'me@myhost.com',
187                                   To       => 'you@yourhost.com',
188                                   Subject  => "Hello, nurse!");
189
190        ### Attachment #1: a simple text document:
191        $top->attach(Path=>"./testin/short.txt");
192
193        ### Attachment #2: a GIF file:
194        $top->attach(Path        => "./docs/mime-sm.gif",
195                     Type        => "image/gif",
196                     Encoding    => "base64");
197
198        ### Attachment #3: text we'll create with text we have on-hand:
199        $top->attach(Data => $contents);
200
201       The MailBox equivalent could be
202
203        my $msg = Mail::Message->build
204          ( From     => 'me@myhost.com'
205          , To       => 'you@yourhost.com'
206          , Subject  => "Hello, nurse!"
207
208          , file     => "./testin/short.txt"
209          , file     => "./docs/mime-sm.gif"
210          , data     => $contents
211          );
212
213       One of the simplifications is that MIME::Types is used to lookup the
214       right content type and optimal transfer encoding.  Good values for
215       content-disposition and such are added as well.
216
217       build, starting with nothing
218
219       See build().
220
221       buildFromBody, body becomes message
222
223       See buildFromBody().
224
225       The Content-* fields
226
227       The various "Content-*" fields are not as harmless as they look.  For
228       instance, the "Content-Type" field will have an effect on the default
229       transfer encoding.
230
231       When a message is built this way:
232
233        my $msg = Mail::Message->build
234         ( 'Content-Type' => 'video/mpeg3'
235         , 'Content-Transfer-Encoding' => 'base64'
236         , 'Content-Disposition' => 'attachment'
237         , file => '/etc/passwd'
238         );
239
240       then first a "text/plain" body is constructed (MIME::Types does not
241       find an extension on the filename so defaults to "text/plain"), with no
242       encoding.  Only when that body is ready, the new type and requested
243       encodings are set.  The content of the body will get base64 encoded,
244       because it is requested that way.
245
246       What basically happens is this:
247
248        my $head = ...other header lines...;
249        my $body = Mail::Message::Body::Lines->new(file => '/etc/passwd');
250        $body->type('video/mpeg3');
251        $body->transferEncoding('base64');
252        $body->disposition('attachment');
253        my $msg  = Mail::Message->buildFromBody($body, $head);
254
255       A safer way to construct the message is:
256
257        my $body = Mail::Message::Body::Lines->new
258         ( file              => '/etc/passwd'
259         , mime_type         => 'video/mpeg3'
260         , transfer_encoding => 'base64'
261         , disposition       => 'attachment'
262         );
263
264        my $msg  = Mail::Message->buildFromBody
265         ( $body
266         , ...other header lines...
267         );
268
269       In the latter program, you will immediately start with a body of the
270       right type.
271

DIAGNOSTICS

273       Error: Only build() Mail::Message's; they are not in a folder yet
274           You may wish to construct a message to be stored in a some kind of
275           folder, but you need to do that in two steps.  First, create a
276           normal Mail::Message, and then add it to the folder.  During this
277           Mail::Box::addMessage() process, the message will get coerce()-d
278           into the right message type, adding storage information and the
279           like.
280

SEE ALSO

282       This module is part of Mail-Message distribution version 3.013, built
283       on June 24, 2023. Website: http://perl.overmeer.net/CPAN/
284

LICENSE

286       Copyrights 2001-2023 by [Mark Overmeer <markov@cpan.org>]. For other
287       contributors see ChangeLog.
288
289       This program is free software; you can redistribute it and/or modify it
290       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
291
292
293
294perl v5.38.0                      2023-07-20Mail::Message::Construct::Build(3)
Impressum