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.018
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 As you can see from the synopsis, all methods that modify the
127 Email::Stuffer object returns the object, and thus most normal calls
128 are chainable.
129 However, please note that "send", and the group of methods that do not
131 change the Email::Stuffer object do not return the object, and thus are
132 not chainable.
133 new
135 Creates a new, empty, Email::Stuffer object.
136 You can pass a hashref of properties to set, including:
138 • to
140 • from
142 • cc
144 • bcc
146 • reply_to
148 • subject
150 • text_body
152 • html_body
154 • transport
156 The to, cc, bcc, and reply_to headers properties may be provided as
158 array references. The array's contents will be used as the list of
159 arguments to the setter.
160 header_names
162 Returns, as a list, all of the headers currently set for the Email For
163 backwards compatibility, this method can also be called as B[headers].
164 parts
166 Returns, as a list, the Email::MIME parts for the Email
167 header $header => $value
169 Sets a named header in the email. Multiple calls with the same $header
170 will overwrite previous calls $value.
171 to @addresses
173 Sets the To: header in the email
174 from $address
176 Sets the From: header in the email
177 reply_to $address
179 Sets the Reply-To: header in the email
180 cc @addresses
182 Sets the Cc: header in the email
183 bcc @addresses
185 Sets the Bcc: header in the email
186 subject $text
188 Sets the Subject: header in the email
189 text_body $body [, $attribute => $value, ... ]
191 Sets the text body of the email. Appropriate headers are set for you.
192 You may override MIME attributes as needed. See the "attributes"
193 parameter to "create" in Email::MIME for the headers you can set.
194 If $body is undefined, this method will do nothing.
196 Prior to Email::Stuffer version 0.015 text body was marked as flowed,
198 which broke all pre-formated body text. Empty space at the beggining
199 of the line was dropped and every new line character could be changed
200 to one space (and vice versa). Version 0.015 (and later) does not set
201 flowed format automatically anymore and so text body is really plain
202 text. If you want to use old behavior of "advanced" flowed formatting,
203 set flowed format manually by: "text_body($body, format => 'flowed')".
204 html_body $body [, $header => $value, ... ]
206 Sets the HTML body of the email. Appropriate headers are set for you.
207 You may override MIME attributes as needed. See the "attributes"
208 parameter to "create" in Email::MIME for the headers you can set.
209 If $body is undefined, this method will do nothing.
211 attach $contents [, $attribute => $value, ... ]
213 Adds an attachment to the email. The first argument is the file
214 contents followed by (as for text_body and html_body) the list of
215 headers to use. Email::Stuffer will try to guess the headers
216 correctly, but you may wish to provide them anyway to be sure. Encoding
217 is Base64 by default. See the "attributes" parameter to "create" in
218 Email::MIME for the headers you can set.
219 attach_file $file [, $attribute => $value, ... ]
221 Attachs a file that already exists on the filesystem to the email.
222 "attach_file" will attempt to auto-detect the MIME type, and use the
223 file's current name when attaching. See the "attributes" parameter to
224 "create" in Email::MIME for the headers you can set.
225 transport
227 $stuffer->transport( $moniker, @options )
228 or
230 $stuffer->transport( $transport_obj )
232 The "transport" method specifies the Email::Sender transport that you
234 want to use to send the email, and any options that need to be used to
235 instantiate the transport. $moniker is used as the transport name; if
236 it starts with an equals sign ("=") then the text after the sign is
237 used as the class. Otherwise, the text is prepended by
238 "Email::Sender::Transport::".
239 Alternatively, you can pass a complete transport object (which must be
241 an Email::Sender::Transport object) and it will be used as is.
242 email
244 Creates and returns the full Email::MIME object for the email.
245 as_string
247 Returns the string form of the email. Identical to (and uses behind the
248 scenes) Email::MIME->as_string.
249 send
251 $stuffer->send;
252 or
254 $stuffer->send({ to => [ $to_1, $to_2 ], from => $sender });
256 Sends the email via Email::Sender::Simple. Envelope information can be
258 specified in a hash reference.
259 On failure, returns false.
261 send_or_die
263 $stuffer->send_or_die;
264 or
266 $stuffer->send_or_die({ to => [ $to_1, $to_2 ], from => $sender });
268 Sends the email via Email::Sender::Simple. Envelope information can be
270 specified in a hash reference.
271 On failure, throws an exception.
273
275 Here is another example (maybe plural later) of how you can use
276 Email::Stuffer's brevity to your advantage.
277 Custom Alerts
279 package SMS::Alert;
280 use base 'Email::Stuffer';
281 sub new {
283 shift()->SUPER::new(@_)
284 ->from('monitor@my.website')
285 # Of course, we could have pulled these from
286 # $MyConfig->{support_tech} or something similar.
287 ->to('0416181595@sms.gateway')
288 ->transport('SMTP', { host => '123.123.123.123' });
289 }
290 package My::Code;
292 unless ( $Server->restart ) {
294 # Notify the admin on call that a server went down and failed
295 # to restart.
296 SMS::Alert->subject("Server $Server failed to restart cleanly")
297 ->send;
298 }
299
301 • Fix a number of bugs still likely to exist
302 • Write more tests.
304 • Add any additional small bit of automation that isn't too expensive
306
308 Email::MIME, Email::Sender, <http://ali.as/>
309
311 • Adam Kennedy <adamk@cpan.org>
312 • Ricardo SIGNES <rjbs@cpan.org>
314
316 • Aaron W. Swenson <aaron.w.swenson@gmail.com>
317 • adam <adam@88f4d9cd-8a04-0410-9d60-8f63309c3137>
319 • adamk@cpan.org
321 <adamk@cpan.org@88f4d9cd-8a04-0410-9d60-8f63309c3137>
322 • adam@phase-n.com
324 <adam@phase-n.com@88f4d9cd-8a04-0410-9d60-8f63309c3137>
325 • Alastair Douglas <altreus@altre.us>
327 • Aristotle Pagaltzis <pagaltzis@gmx.de>
329 • Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
331 • Chase Whitener <chase.whitener@infotechfl.com>
333 • CosmicNet <webmaster@cosmicperl.com>
335 • Dan Book <grinnz@gmail.com>
337 • John Napiorkowski <jjn1056@yahoo.com>
339 • Josh Stompro <github@stompro.org>
341 • Kevin Tew <tewk@tan.tewk.com>
343 • Kieren Diment <kd@fenchurch.local>
345 • Kris Matthews <krismatth@icloud.com>
347 • Kris Matthews <kris@tigerlms.com>
349 • Lee Johnson <lee@givengain.ch>
351 • Manni Heumann <github@lxxi.org>
353 • Pali <pali@cpan.org>
355 • Ricardo Signes <rjbs@semiotic.systems>
357 • Ross Attrill <ross.attrill@gmail.com>
359 • Russell Jenkins <russell.jenkins@strategicdata.com.au>
361 • Shawn Sorichetti <shawn@coloredblocks.com>
363 • Steve Dondley <s@dondley.com>
365 • tokuhirom <tokuhirom@gmail.com>
367
369 This software is copyright (c) 2004 by Adam Kennedy and Ricardo SIGNES.
370 This is free software; you can redistribute it and/or modify it under
372 the same terms as the Perl 5 programming language system itself.
373perl v5.34.0 2021-07-22 Email::Stuffer(3)