-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
440 lines (322 loc) · 14 KB
/
README
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
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
NAME
Mail::Builder - Easily create plaintext/html e-mail messages with
attachments and inline images
SYNOPSIS
use Mail::Builder;
my $mail = Mail::Builder->new({
subject => 'Party at Sam\'s place',
from => 'mightypirate@meele-island.mq',
htmltext => '<h1>Party invitation</h1> ... ',
attachment=> '/path/to/direction_samandmax.pdf',
});
# Alter from name
$mail->from->name('Guybrush Threepwood');
# Set recipent
$mail->to('manuel.calavera@dod.mx','Manuel Calavera');
# Add one more recipient
$mail->to->add('glotis@dod.mx');
# Send it with your favourite module (e.g. Email::Send)
my $mailer = Email::Send->new({mailer => 'Sendmail'})->send($mail->stringify);
# Or mess with MIME::Entity objects
my $mime = $mail->build_message;
$mime-> ....
DESCRIPTION
This module helps you to build correct e-mails with attachments, inline
images, multiple recipients, ... without having to worry about the
underlying MIME and encoding issues. Mail::Builder relies heavily on the
MIME::Entity module from the MIME::Tools distribution.
The module will create the correct MIME bodies, headers and containers
(multipart/mixed, multipart/related, multipart/alternative) depending on
if you use attachments, HTML text and inline images.
Furthermore it will encode non-ascii header data and autogenerate
plaintext messages (if you don't provide it yourself or disable the
autotext option) from html content.
Addresses, attachments and inline images are handled as objects by
helper classes:
* Mail::Builder::Address
Stores an e-mail address and a display name.
* Attachments: Mail::Builder::Attachment
This class manages attachments which can be created either from
files in the filesystem, filehandles or from data in memory.
* Inline images:Mail::Builder::Image
The Mail::Builder::Image class manages images that should be
displayed in the html e-mail body. (<img src="cid:imageid" />)
* Mail::Builder::List
Helper class for handling list of varoius items (i.e. recipient
lists, attachment lists and image lists)
METHODS
Constructors
new
This is a simple constructor. It accepts all defined acccessors as a
Hash orr HashRef.
Public methods
stringify
Returns the e-mail message as a string. This string can be passed to
modules like Email::Send.
This method is just a shortcut to "$mb->build_message->stringify"
build_message
my $entity = $mb->build_message();
# Print the entire message:
$entity->print(\*STDOUT);
# Stringify the entire message:
print $entity->stringify;
Returns the e-mail message as a MIME::Entity object. You can mess around
with the object, change parts, ... as you wish.
Every time you call build_message the MIME::Entity object will be
created, which can take some time if you are sending bulk e-mails. In
order to increase the processing speed Mail::Builder::Attachment and
Mail::Builder::Image entities will be cached and only rebuilt if
something has changed.
Each call to this method also changes the "messageid".
purge_cache
Emptys the attachment and image cache and removes the plaintext text if
it has been autogenerated from html text. Also deletes the Message ID.
Accessors
from, returnpath, reply, sender
These accessors set/return the from, sender and reply address as well as
the returnpath for bounced messages.
$obj->from(EMAIL[,NAME[,COMMENT]])
OR
$obj->from(Mail::Builder::Address)
OR
$obj->from(Email::Address)
OR
$obj->from({
email => EMAIL,
[name => NAME,]
[comment => COMMENT,]
});
This accessor always returns a Mail::Builder::Address object.
To change the attribute value you can either supply
* a Mail::Builder::Address object
* an Email::Address object
* a list containing an e-mail address and optionally name and comment
* a HashRef that will be passed to the Mail::Builder::Address
constructor (Keys: email, name and comment)
The presence of a value can be checked with the "has_from", "has_reply",
"has_reply" and "has_sender" methods.
Values can be cleared with the "clear_from", "clear_reply",
"clear_reply" and "clear_sender" methods.
to, cc, bcc
$obj->to(Mail::Builder::List)
OR
$obj->to(Mail::Builder::Address)
OR
$obj->to(Email::Address)
OR
$obj->to(EMAIL[,NAME[,COMMENT]])
OR
$obj->to({
email => EMAIL,
[name => NAME,]
[comment => COMMENT,]
})
OR
$obj->to([
Mail::Builder::Address | Email::Address | HashRef | EMAIL
])
This accessor always returns a Mail::Builder::List object containing
Mail::Builder::Address objects.
To alter the values you can either
* Manipulate the Mail::Builder::List object (add, remove, ...)
* Supply a Mail::Builder::Address object. This will reset the current
list and add the object to the list.
* Supply a Mail::Builder::List object. The list object replaces the
old one if the list types matches.
* Scalar and HashRef values will be passed to
"Mail::Builder::Address->new". The returned object will be added to
the object list.
* Supply a Email::Address object. This will reset the current list,
generate a Mail::Builder::Address object and add it to the list.
The Mail::Builder::List package provides some basic methods for
manipulating the list of recipients. e.g.
$obj->to->add(EMAIL[,NAME[,COMMENT]])
OR
$obj->to->add(Mail::Builder::Address)
OR
$obj->to->add(Email::Address)
language
e-mail text language. Additionally the "has_language" and
"clear_language" methods can be used to check respectively clear the
value.
messageid
Message ID of the e-mail as a Email::MessageID object. Read only and
available only after the "build_message" or "stingify" methods have been
called. Each call to "build_message" or "stingify" changes the message
ID.
organization
Accessor for the name of the sender's organisation. This header field is
not part of the RFC 4021, however supported by many mailer applications.
Additionally the "has_organization" and "clear_organization" methods can
be used to check or clear the value.
priority
Priority accessor. Accepts values from 1 to 5. The default priority is
3.
subject
e-mail subject accessor. Must be specified.
htmltext
HTML mail body accessor. Additionally the "has_htmltext" and
"clear_htmltext" methods can be used to check or clear the value.
mailer
Mailer name.
plaintext
Plaintext mail body accessor. The "clear_plaintext" and "has_plaintext"
methods can be used to check or clear the value.
This text will be autogenerated from htmltext if not provided by the
user and the "autotext" option is not turned off. Simple formating (e.g.
<strong>, <em>) will be converted to pseudo formating.
If you want to disable the autogeneration of plaintext parts set the
autotext accessor to a false value. However be aware that most anti-spam
enginges tag html e-mail messages without a plaintext part as spam.
The following html tags will be transformed to simple markup:
* I, EM
Italic text will be surrounded by underscores. (_italic text_)
* H1, H2, H3, ...
Two equal signs are prepended to headlines (== Headline)
* STRONG, B
Bold text will be marked by stars (*bold text*)
* HR
A horizontal rule is replaced with 60 dashes.
* BR
Single linebreak
* P, DIV
Two linebreaks
* IMG
Prints the alt text of the image (if any).
* A
Prints the link url surrounded by brackets ([http://myurl.com text])
* UL, OL
All list items will be indented with a tab and prefixed with a start
(*) or an index number.
* TABLE, TR, TD, TH
Tables are converted into text using Text::Table.
autotext
Enables the autogeneration of plaintext parts from HTML.
Default TRUE.
attachment
$obj->attachment(Mail::Builder::List)
OR
$obj->attachment(Mail::Builder::Attachment)
OR
$obj->attachment(PATH | Path::Class::File | FH | IO::File | SCALARREF)
OR
$obj->attachment({
file => PATH | Path::Class::File | FH | IO::File | SCALARREF,
[name => NAME,]
[mimetype => MIME,]
})
OR
$obj->attachment([
HashRef | Mail::Builder::Attachment | PATH | Path::Class::File | FH | IO::File | SCALARREF
]);
This accessor always returns a Mail::Builder::List object. If you supply
a Mail::Builder::List the list will be replaced.
If you pass a Mail::Builder::Attachment object, a filehandle, an
IO::File object, a Path::Class::File object, a path or a scalar
reference or a scalar path the current list will be reset and the new
attachment will be added.
The Mail::Builder::List package provides some basic methods for
manipulating the list of attachments.
If you want to append an additional attachment to the list use
$obj->attachment->add(PATH | Path::Class::File | FH | IO::File | ScalarRef)
OR
$obj->attachment->add({
file => PATH | Path::Class::File | FH | IO::File | ScalarRef,
[name => NAME,]
[mimetype => MIME,]
})
OR
$obj->attachment->add(Mail::Builder::Attachment)
image
$obj->image(Mail::Builder::List)
OR
$obj->image(Mail::Builder::Image)
OR
$obj->image(PATH | Path::Class::File | FH | IO::File | ScalarRef)
OR
$obj->image({
file => PATH | Path::Class::File | FH | IO::File | ScalarRef,
[id => ID,]
[mimetype => MIME,]
})
OR
$obj->image([
HashRef | Mail::Builder::Image | PATH | Path::Class::File | FH | IO::File | ScalarRef
]);
This accessor always returns a Mail::Builder::List object. If you supply
a Mail::Builder::List the list will be replaced.
If you pass a Mail::Builder::Image object or a scalar path (with an
optional id) the current list will be reset and the new image will be
added.
The Mail::Builder::List package provides some basic methods for
manipulating the list of inline images.
If you want to append an additional attachment to the list use
$obj->image->add(PATH | Path::Class::File | FH | IO::File | ScalarRef)
OR
$obj->image->add(Mail::Builder::Image)
You can embed the image into the html mail body code by referencing the
ID. If you don't provide an ID the lowercase filename without the file
extension will be used as the ID.
<img src="cid:logo"/>
Only jpg, gif and png images may be added as inline images.
EXAMPLE
If you want to send multiple e-mail messages from one Mail::Builder
object (e.g. a solicited mailing to multiple recipients) you have to pay
special attention, or else you might end up with growing recipients
lists.
# Example for a mass mailing
foreach my $recipient (@recipients) {
$mb->to->reset; # Remove all recipients
$mb->to->add($recipient); # Add current recipient
# Alternatively you could use $mb->to($recipient); which has the
# same effect as the two previous commands. Same applies to 'cc' and 'bcc'
# Autogenerated Plaintext will be reset
$mb->htmltext(qq[<h1>Hello $recipient!</h1> Text, yadda yadda! ]);
# Plaintext is autogenerated
my $mail = $mb->stringify();
# Send $mail ...
}
IMPORTANT CHANGES
From 1.10 on Mail::Builder only supports utf-8 charsets for mails.
Supporting multiple encodings turned out to be error prone and not
necessary since all modern mail clients support utf-8.
Starting with Mail::Builder 2.0 the Mail::Builder::Attachment::* and
Mail::Builder::Image::* classes have been deprecated. Use the base
classes Mail::Builder::Attachment and Mail::Builder::Image instead.
CAVEATS
Watch out when sending Mail::Builder generated mails with
Email::Send::SMTP: The 'Return-Path' headers are ignored by the MTA
since Email::Send::SMTP uses the 'From' header for SMTP handshake.
Postfix (any maybe some other MTAs) overwrites the 'Return-Path' field
in the data with the e-mail used in the handshake ('From'). The
behaviour of Email::Send::SMTP may however be modified by replacing the
"get_env_sender" and "get_env_recipients" methods. See Email::Send::SMTP
for more details.
SUPPORT
Please report any bugs or feature requests to
"bug-mail-builder@rt.cpan.org", or through the web interface at
<http://rt.cpan.org/Public/Bug/Report.html?Queue=Mail::Builder>. I will
be notified, and then you'll automatically be notified of progress on
your report as I make changes.
AUTHOR
Maroš Kollár
CPAN ID: MAROS
maros [at] k-1.com
http://www.k-1.com
COPYRIGHT
Mail::Builder is Copyright (c) 2007-2010 Maroš Kollár.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself as long it is not used for sending
unsolicited mail (SPAM):
"Thou shalt not send SPAM with this module."
The full text of the license can be found in the LICENSE file included
with this module.
SEE ALSO
The Mime::Entity module in the Mime::Tools distribution.
Mail::Builder::Simple provides a wrapper around this module and
itegrates it with Email::Sender::Simple
Furthermore these modules are being used for various tasks:
* Email::Valid for validating e-mail addresses
* Email::MessageID for generating unique message IDs
* HTML::TreeBuilder for parsing html and generating plaintext
* MIME::Types for guessing attachment mime types