1Mail::Message::ConstrucUts:e:rBuCiolndt(r3i)buted Perl DMoaciulm:e:nMteastsiaogne::Construct::Build(3)
2
6 Mail::Message::Construct::Build - building a Mail::Message from
7 components
8
10 my $msg1 = Mail::Message->build
11 ( From => 'me', data => "only two\nlines\n");
12 my $msg2 = Mail::Message->buildFromBody($body);
14 Mail::Message->build
16 ( From => 'me@myhost.com'
17 , To => 'you@yourhost.com'
18 , Subject => "Read our folder!"
19 , data => \@lines
21 , file => 'folder.pdf'
22 )->send(via => 'postfix');
23
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
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 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 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 This "build" method will use buildFromBody() when the body object
53 has been constructed. Together, they produce your message.
54 -Option--Default
56 attach undef
57 data undef
58 file undef
59 files [ ]
60 head undef
61 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 attach => $folder->message(3)->decoded # body
69 attach => $folder->message(3) # message
70 attach => [ $msg1, $msg2->part(6), $msg3->body ];
71 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 data => [ "line 1\n", "line 2\n" ] # array of lines
79 data => <<'TEXT' # string
80 line 1
81 line 2
82 TEXT
83 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 my $in = IO::File->new('/etc/passwd', 'r');
91 file => 'picture.jpg' # filename
93 file => \*MYINPUTFILE # file handle
94 file => $in # any IO::Handle
95 files => [ 'picture.jpg', \*MYINPUTFILE, $in ]
96 open my $in, '<:raw', '/etc/passwd'; # alternative for IO::File
98 files => ARRAY-OF-FILE
100 Alias for option "file".
101 head => HEAD
103 Start with a prepared header, otherwise one is created.
104 example:
106 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 , 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 my $msg = Mail::Message->build
121 ( To => 'you'
122 , 'Content-Type' => 'text/html'
123 , data => "<html></html>"
124 );
125 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 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 A "Date", "Message-Id", and "MIME-Version" field are added unless
141 supplied.
142 example:
144 my $type = Mail::Message::Field->new('Content-Type', 'text/html'
146 , 'charset="us-ascii"');
147 my @to = ( Mail::Address->new('Your name', 'you@example.com')
149 , 'world@example.info'
150 );
151 my $msg = Mail::Message->buildFromBody
153 ( $body
154 , From => 'me@example.nl'
155 , To => \@to
156 , $type
157 );
158
160 Building a message
161 Rapid building
162 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 Compared to MIME::Entity::build()
168 The "build" method in MailBox is modelled after the "build" method as
170 provided by MIMETools, but with a few simplifications:
171 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 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 ### 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 ### Attachment #1: a simple text document:
191 $top->attach(Path=>"./testin/short.txt");
192 ### Attachment #2: a GIF file:
194 $top->attach(Path => "./docs/mime-sm.gif",
195 Type => "image/gif",
196 Encoding => "base64");
197 ### Attachment #3: text we'll create with text we have on-hand:
199 $top->attach(Data => $contents);
200 The MailBox equivalent could be
202 my $msg = Mail::Message->build
204 ( From => 'me@myhost.com'
205 , To => 'you@yourhost.com'
206 , Subject => "Hello, nurse!"
207 , file => "./testin/short.txt"
209 , file => "./docs/mime-sm.gif"
210 , data => $contents
211 );
212 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 build, starting with nothing
218 See build().
220 buildFromBody, body becomes message
222 See buildFromBody().
224 The Content-* fields
226 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 When a message is built this way:
232 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 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 What basically happens is this:
247 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 A safer way to construct the message is:
256 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 my $msg = Mail::Message->buildFromBody
265 ( $body
266 , ...other header lines...
267 );
268 In the latter program, you will immediately start with a body of the
270 right type.
271
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
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
286 Copyrights 2001-2023 by [Mark Overmeer <markov@cpan.org>]. For other
287 contributors see ChangeLog.
288 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/
291perl v5.38.0 2023-07-20Mail::Message::Construct::Build(3)