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