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 compo‐
7 nents
8
10 my $msg3 = Mail::Message->build
11 (From => 'me', data => "only two\nlines\n");
12 my $msg4 = Mail::Message->buildFromBody($body);
14
16 Complex functionality on Mail::Message objects is implemented in dif‐
17 ferent files which are autoloaded. This file implements the function‐
18 ality related to building of messages from various components.
19
21 Constructing a message
22 Mail::Message->build([MESSAGE⎪PART⎪BODY], CONTENT)
24 Simplified message object builder. In case a MESSAGE or message
26 PART is specified, a new message is created with the same body to
27 start with, but new headers. A BODY may be specified as well.
28 However, there are more ways to add data simply.
29 The CONTENT is a list of key-value pairs and header field objects.
31 The keys which start with a capital are used as header-lines.
32 Lower-cased fields are used for other purposes as listed below.
33 Each field may be used more than once. Pairs where the value is
34 "undef" are ignored.
35 If more than one "data", "file", and "attach" is specified, a
37 multi-parted message is created. Some "Content-" fields are
38 treated separately: to enforce the content lines of the produced
39 message body after it has been created. For instance, to explic‐
40 itly state that you wish a "multipart/alternative" in stead of the
41 default "multipart/mixed". If you wish to specify the type per
42 datum, you need to start playing with Mail::Message::Body objects
43 yourself.
44 This "build" method will use buildFromBody() when the body object
46 has been constructed. Together, they produce your message.
47 Option--Default
49 attach undef
50 data undef
51 file undef
52 files [ ]
53 head undef
54 . attach BODY⎪PART⎪MESSAGE⎪ARRAY
56 One attachment to the message. Each attachment can be full
58 MESSAGE, a PART, or a BODY. Any MESSAGE will get encapsulated
59 into a "message/rfc822" body. You can specify many items (may
60 be of different types) at once.
61 attach => $folder->message(3)->decoded # body
63 attach => $folder->message(3) # message
64 attach => [ $msg1, $msg2->part(6), $msg3->body ];
65 . data STRING⎪ARRAY-OF-LINES
67 The text for one part, specified as one STRING, or an ARRAY of
69 lines. Each line, including the last, must be terminated by a
70 newline. This argument is passed to Mail::Mes‐
71 sage::Body::new(data) to construct one.
72 data => [ "line 1\n", "line 2\n" ] # array of lines
74 data => <<'TEXT' # string
75 line 1
76 line 2
77 TEXT
78 . file FILENAME⎪FILEHANDLE⎪IOHANDLE
80 Create a body where the data is read from the specified FILE‐
82 NAME, FILEHANDLE, or object of type IO::Handle. Also this body
83 is used to create a Mail::Message::Body.
84 my $in = IO::File->new('/etc/passwd', 'r');
86 file => 'picture.jpg' # filename
88 file => \*MYINPUTFILE # file handle
89 file => $in # any IO::Handle
90 open my $in, '<', '/etc/passwd'; # alternative for IO::File
92 . files ARRAY-OF-FILE
94 See option file, but then an array reference collection more of
96 them.
97 . head HEAD
99 Start with a prepared header, otherwise one is created.
101 Example:
103 my $msg = Mail::Message->build
105 ( From => 'me@home.nl'
106 , To => Mail::Address->new('your name', 'you@yourplace.aq')
107 , Cc => 'everyone@example.com'
108 , $other_message->get('Bcc')
109 , data => [ "This is\n", "the first part of\n", "the message\n" ]
111 , file => 'myself.gif'
112 , file => 'you.jpg'
113 , attach => $signature
114 );
115 my $msg = Mail::Message->build
117 ( To => 'you'
118 , 'Content-Type' => 'text/html'
119 , data => "<html></html>"
120 );
121 Mail::Message->buildFromBody(BODY, [HEAD], HEADERS)
123 Shape a message around a BODY. Bodies have information about their
125 content in them, which is used to construct a header for the mes‐
126 sage. You may specify a HEAD object which is pre-initialized, or
127 one is created for you (also when HEAD is "undef"). Next to that,
128 more HEADERS can be specified which are stored in that header.
129 Header fields are added in order, and before the header lines as
131 defined by the body are taken. They may be supplied as key-value
132 pairs or Mail::Message::Field objects. In case of a key-value
133 pair, the field's name is to be used as key and the value is a
134 string, address (Mail::Address object), or array of addresses.
135 A "Date", "Message-Id", and "MIME-Version" field are added unless
137 supplied.
138 Example:
140 my $type = Mail::Message::Field->new('Content-Type', 'text/html'
142 , 'charset="us-ascii"');
143 my @to = ( Mail::Address->new('Your name', 'you@example.com')
145 , 'world@example.info'
146 );
147 my $msg = Mail::Message->buildFromBody
149 ( $body
150 , From => 'me@example.nl'
151 , To => \@to
152 , $type
153 );
154
156 Building a message
157 Rapid building
159 Most messages you need to construct are relatively simple. Therefore,
161 this module provides a method to prepare a message with only one method
162 call: build().
163 Compared to MIME::Entity::build()
165 The "build" method in MailBox is modelled after the "build" method as
167 provided by MIMETools, but with a few simplifications:
168 When a keys starts with a capital, than it is always a header field
170 When a keys is lower-cased, it is always something else
171 You use the real field-names, not abbreviations
172 All field names are accepted
173 You may specify field objects between key-value pairs
174 A lot of facts are auto-detected, like content-type and encoding
175 You can create a multipart at once
176 Hum, reading the list above... what is equivalent? MIME::Entity is not
178 that simple after all! Let's look at an example from MIME::Entity's
179 manual page:
180 ### Create the top-level, and set up the mail headers:
182 $top = MIME::Entity->build(Type => "multipart/mixed",
183 From => 'me@myhost.com',
184 To => 'you@yourhost.com',
185 Subject => "Hello, nurse!");
186 ### Attachment #1: a simple text document:
188 $top->attach(Path=>"./testin/short.txt");
189 ### Attachment #2: a GIF file:
191 $top->attach(Path => "./docs/mime-sm.gif",
192 Type => "image/gif",
193 Encoding => "base64");
194 ### Attachment #3: text we'll create with text we have on-hand:
196 $top->attach(Data => $contents);
197 The MailBox equivalent could be
199 my $msg = Mail::Message->build
201 ( From => 'me@myhost.com'
202 , To => 'you@yourhost.com'
203 , Subject => "Hello, nurse!"
204 , file => "./testin/short.txt"
206 , file => "./docs/mime-sm.gif"
207 , data => $contents
208 );
209 One of the simplifications is that MIME::Types is used to lookup the
211 right content type and optimal transfer encoding. Good values for con‐
212 tent-disposition and such are added as well.
213 build, starting with nothing
215 See build().
217 buildFromBody, body becomes message
219 See buildFromBody().
221 The Content-* fields
223 The various "Content-*" fields are not as harmless as they look. For
225 instance, the "Content-Type" field will have an effect on the default
226 transfer encoding.
227 When a message is built this way:
229 my $msg = Mail::Message->build
231 ( 'Content-Type' => 'video/mpeg3'
232 , 'Content-Transfer-Encoding' => 'base64'
233 , 'Content-Disposition' => 'attachment'
234 , file => '/etc/passwd'
235 );
236 then first a "text/plain" body is constructed (MIME::Types does not
238 find an extension on the filename so defaults to "text/plain"), with no
239 encoding. Only when that body is ready, the new type and requested
240 encodings are set. The content of the body will get base64 encoded,
241 because it is requested that way.
242 What basically happens is this:
244 my $head = ...other header lines...;
246 my $body = Mail::Message::Body::Lines->new(file => '/etc/passwd');
247 $body->type('video/mpeg3');
248 $body->transferEncoding('base64');
249 $body->diposition('attachment');
250 my $msg = Mail::Message->buildFromBody($body, $head);
251 A safer way to construct the message is:
253 my $body = Mail::Message::Body::Lines->new
255 ( file => '/etc/passwd'
256 , mime_type => 'video/mpeg3'
257 , transfer_encoding => 'base64'
258 , disposition => 'attachment'
259 );
260 my $msg = Mail::Message->buildFromBody
262 ( $body
263 , ...other header lines...
264 );
265 In the latter program, you will immediately start with a body of the
267 right type.
268
270 Error: Only build() Mail::Message's; they are not in a folder yet
271 You may wish to construct a message to be stored in a some kind of
273 folder, but you need to do that in two steps. First, create a normal
274 Mail::Message, and then add it to the folder. During this
275 Mail::Box::addMessage() process, the message will get coerce()-d into
276 the right message type, adding storage information and the like.
277
279 This module is part of Mail-Box distribution version 2.070, built on
280 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
281
283 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
284 ChangeLog.
285 This program is free software; you can redistribute it and/or modify it
287 under the same terms as Perl itself. See
288 http://www.perl.com/perl/misc/Artistic.html
289perl v5.8.8 2007-03-25Mail::Message::Construct::Build(3)