1Email::Stuffer(3) User Contributed Perl Documentation Email::Stuffer(3)
2
6 Email::Stuffer - A more casual approach to creating and sending Email::
7 emails
8
10 version 0.020
11
13 # Prepare the message
14 my $body = <<'AMBUSH_READY';
15 Dear Santa
16 I have killed Bun Bun.
18 Yes, I know what you are thinking... but it was actually a total accident.
20 I was in a crowded line at a BayWatch signing, and I tripped, and stood on
22 his head.
23 I know. Oops! :/
25 So anyways, I am willing to sell you the body for $1 million dollars.
27 Be near the pinhole to the Dimension of Pain at midnight.
29 Alias
31 AMBUSH_READY
33 # Create and send the email in one shot
35 Email::Stuffer->from ('cpan@ali.as' )
36 ->to ('santa@northpole.org' )
37 ->bcc ('bunbun@sluggy.com' )
38 ->text_body($body )
39 ->attach_file('dead_bunbun_faked.gif' )
40 ->send;
41
43 The basics should all work, but this module is still subject to name
44 and/or API changes
45 Email::Stuffer, as its name suggests, is a fairly casual module used to
47 stuff things into an email and send them. It is a high-level module
48 designed for ease of use when doing a very specific common task, but
49 implemented on top of the light and tolerable Email:: modules.
50 Email::Stuffer is typically used to build emails and send them in a
52 single statement, as seen in the synopsis. And it is certain only for
53 use when creating and sending emails. As such, it contains no email
54 parsing capability, and little to no modification support.
55 To re-iterate, this is very much a module for those "slap it together
57 and fire it off" situations, but that still has enough grunt behind the
58 scenes to do things properly.
59 Default Transport
61 Although it cannot be relied upon to work, the default behaviour is to
62 use "sendmail" to send mail, if you don't provide the mail send channel
63 with either the "transport" method, or as an argument to "send".
64 (Actually, the choice of default is delegated to Email::Sender::Simple,
66 which makes its own choices. But usually, it uses "sendmail".)
67 Why use this?
69 Why not just use Email::Simple or Email::MIME? After all, this just
70 adds another layer of stuff around those. Wouldn't using them directly
71 be better?
72 Certainly, if you know EXACTLY what you are doing. The docs are clear
74 enough, but you really do need to have an understanding of the
75 structure of MIME emails. This structure is going to be different
76 depending on whether you have text body, HTML, both, with or without an
77 attachment etc.
78 Then there's brevity... compare the following roughly equivalent code.
80 First, the Email::Stuffer way.
82 Email::Stuffer->to('Simon Cozens<simon@somewhere.jp>')
84 ->from('Santa@northpole.org')
85 ->text_body("You've been good this year. No coal for you.")
86 ->attach_file('choochoo.gif')
87 ->send;
88 And now doing it directly with a knowledge of what your attachment is,
90 and what the correct MIME structure is.
91 use Email::MIME;
93 use Email::Sender::Simple;
94 use IO::All;
95 Email::Sender::Simple->try_to_send(
97 Email::MIME->create(
98 header => [
99 To => 'simon@somewhere.jp',
100 From => 'santa@northpole.org',
101 ],
102 parts => [
103 Email::MIME->create(
104 body => "You've been a good boy this year. No coal for you."
105 ),
106 Email::MIME->create(
107 body => io('choochoo.gif'),
108 attributes => {
109 filename => 'choochoo.gif',
110 content_type => 'image/gif',
111 },
112 ),
113 ],
114 );
115 );
116 Again, if you know MIME well, and have the patience to manually code up
118 the Email::MIME structure, go do that, if you really want to.
119 Email::Stuffer as the name suggests, solves one case and one case only:
121 generate some stuff, and email it to somewhere, as conveniently as
122 possible. DWIM, but do it as thinly as possible and use the solid
123 Email:: modules underneath.
124
126 This library should run on perls released even a long time ago. It
127 should work on any version of perl released in the last five years.
128 Although it may work on older versions of perl, no guarantee is made
130 that the minimum required version will not be increased. The version
131 may be increased for any reason, and there is no promise that patches
132 will be accepted to lower the minimum required perl.
133
135 As you can see from the synopsis, all methods that modify the
136 Email::Stuffer object returns the object, and thus most normal calls
137 are chainable.
138 However, please note that "send", and the group of methods that do not
140 change the Email::Stuffer object do not return the object, and thus are
141 not chainable.
142 new
144 Creates a new, empty, Email::Stuffer object.
145 You can pass a hashref of properties to set, including:
147 • to
149 • from
151 • cc
153 • bcc
155 • reply_to
157 • subject
159 • text_body
161 • html_body
163 • transport
165 The to, cc, bcc, and reply_to headers properties may be provided as
167 array references. The array's contents will be used as the list of
168 arguments to the setter.
169 header_names
171 Returns, as a list, all of the headers currently set for the Email For
172 backwards compatibility, this method can also be called as B[headers].
173 parts
175 Returns, as a list, the Email::MIME parts for the Email
176 header
178 $stuffer->header($header_name = $value)
179 This method sets a named header in the email. Multiple calls with the
181 same $header_name will overwrite previous calls $value.
182 to
184 $stuffer->to(@addresses)
185 This method sets the To header in the email.
187 from
189 $stuffer->from($address)
190 This method sets the From header in the email.
192 reply_to
194 $stuffer->reply_to($address)
195 This method sets the Reply-To header in the email.
197 cc
199 $stuffer->cc(@addresses)
200 This method sets the Cc header in the email.
202 bcc
204 $stuffer->bcc(@addresses)
205 This method sets the Bcc header in the email.
207 subject
209 $stuffer->subject($text)
210 This method sets the Subject header in the email.
212 text_body
214 $stuffer->text_body($body, %attributes);
215 Sets the text body of the email. Appropriate headers are set for you.
217 You may override MIME attributes as needed. See the "attributes"
218 parameter to "create" in Email::MIME for the headers you can set.
219 If $body is undefined, this method will do nothing.
221 Prior to Email::Stuffer version 0.015 text body was marked as flowed,
223 which broke all pre-formated body text. Empty space at the beggining
224 of the line was dropped and every new line character could be changed
225 to one space (and vice versa). Version 0.015 (and later) does not set
226 flowed format automatically anymore and so text body is really plain
227 text. If you want to use old behavior of "advanced" flowed formatting,
228 set flowed format manually by: "text_body($body, format => 'flowed')".
229 html_body
231 $stuffer->html_body($body, %attributes);
232 Sets the HTML body of the email. Appropriate headers are set for you.
234 You may override MIME attributes as needed. See the "attributes"
235 parameter to "create" in Email::MIME for the headers you can set.
236 If $body is undefined, this method will do nothing.
238 attach
240 $stuffer->attach($contents, %attributes)
241 Adds an attachment to the email. The first argument is the file
243 contents followed by (as for text_body and html_body) the list of
244 headers to use. Email::Stuffer will try to guess the headers
245 correctly, but you may wish to provide them anyway to be sure. Encoding
246 is Base64 by default. See the "attributes" parameter to "create" in
247 Email::MIME for the headers you can set.
248 attach_file
250 $stuffer->attach_file($file, %attributes)
251 Attachs a file that already exists on the filesystem to the email.
253 "attach_file" will attempt to auto-detect the MIME type, and use the
254 file's current name when attaching. See the "attributes" parameter to
255 "create" in Email::MIME for the headers you can set.
256 $file can be a filename or an IO::All::File object.
258 transport
260 $stuffer->transport( $moniker, @options )
261 or
263 $stuffer->transport( $transport_obj )
265 The "transport" method specifies the Email::Sender transport that you
267 want to use to send the email, and any options that need to be used to
268 instantiate the transport. $moniker is used as the transport name; if
269 it starts with an equals sign ("=") then the text after the sign is
270 used as the class. Otherwise, the text is prepended by
271 "Email::Sender::Transport::".
272 Alternatively, you can pass a complete transport object (which must be
274 an Email::Sender::Transport object) and it will be used as is.
275 email
277 my $email_mime = $stuffer->email;
278 This method creates and returns the full Email::MIME object for the
280 email.
281 as_string
283 my $email_document = $stuffer->as_string;
284 Returns the string form of the email. Identical to (and uses behind
286 the scenes) "Email::MIME->as_string".
287 send
289 $stuffer->send;
290 or
292 $stuffer->send({ to => [ $to_1, $to_2 ], from => $sender });
294 Sends the email via Email::Sender::Simple. Envelope information can be
296 specified in a hash reference.
297 On failure, returns false.
299 send_or_die
301 $stuffer->send_or_die;
302 or
304 $stuffer->send_or_die({ to => [ $to_1, $to_2 ], from => $sender });
306 Sends the email via Email::Sender::Simple. Envelope information can be
308 specified in a hash reference.
309 On failure, throws an exception.
311
313 Here is another example (maybe plural later) of how you can use
314 Email::Stuffer's brevity to your advantage.
315 Custom Alerts
317 package SMS::Alert;
318 use base 'Email::Stuffer';
319 sub new {
321 shift()->SUPER::new(@_)
322 ->from('monitor@my.website')
323 # Of course, we could have pulled these from
324 # $MyConfig->{support_tech} or something similar.
325 ->to('0416181595@sms.gateway')
326 ->transport('SMTP', { host => '123.123.123.123' });
327 }
328 package My::Code;
330 unless ( $Server->restart ) {
332 # Notify the admin on call that a server went down and failed
333 # to restart.
334 SMS::Alert->subject("Server $Server failed to restart cleanly")
335 ->send;
336 }
337
339 • Fix a number of bugs still likely to exist
340 • Write more tests.
342 • Add any additional small bit of automation that isn't too expensive
344
346 Email::MIME, Email::Sender, <http://ali.as/>
347
349 • Adam Kennedy <adamk@cpan.org>
350 • Ricardo SIGNES <cpan@semiotic.systems>
352
354 • Aaron W. Swenson <aaron.w.swenson@gmail.com>
355 • adam <adam@88f4d9cd-8a04-0410-9d60-8f63309c3137>
357 • adamk@cpan.org
359 <adamk@cpan.org@88f4d9cd-8a04-0410-9d60-8f63309c3137>
360 • adam@phase-n.com
362 <adam@phase-n.com@88f4d9cd-8a04-0410-9d60-8f63309c3137>
363 • Alastair Douglas <altreus@altre.us>
365 • Aristotle Pagaltzis <pagaltzis@gmx.de>
367 • Chase Whitener <chase.whitener@infotechfl.com>
369 • CosmicNet <webmaster@cosmicperl.com>
371 • Dan Book <grinnz@gmail.com>
373 • fREW Schmidt <frioux@gmail.com>
375 • John Napiorkowski <jjn1056@yahoo.com>
377 • Josh Stompro <github@stompro.org>
379 • Kevin Tew <tewk@tan.tewk.com>
381 • Kieren Diment <kd@fenchurch.local>
383 • Kris Matthews <kris@tigerlms.com>
385 • Lee Johnson <lee@givengain.ch>
387 • Manni Heumann <github@lxxi.org>
389 • Pali <pali@cpan.org>
391 • Ricardo Signes <rjbs@semiotic.systems>
393 • Ross Attrill <ross.attrill@gmail.com>
395 • Russell Jenkins <russell.jenkins@strategicdata.com.au>
397 • Shawn Sorichetti <shawn@coloredblocks.com>
399 • Steve Dondley <s@dondley.com>
401 • tokuhirom <tokuhirom@gmail.com>
403
405 This software is copyright (c) 2004 by Adam Kennedy and Ricardo SIGNES.
406 This is free software; you can redistribute it and/or modify it under
408 the same terms as the Perl 5 programming language system itself.
409perl v5.38.0 2023-07-20 Email::Stuffer(3)