1Email::Stuffer(3)     User Contributed Perl Documentation    Email::Stuffer(3)
2
3
4

NAME

6       Email::Stuffer - A more casual approach to creating and sending Email::
7       emails
8

VERSION

10       version 0.020
11

SYNOPSIS

13         # Prepare the message
14         my $body = <<'AMBUSH_READY';
15         Dear Santa
16
17         I have killed Bun Bun.
18
19         Yes, I know what you are thinking... but it was actually a total accident.
20
21         I was in a crowded line at a BayWatch signing, and I tripped, and stood on
22         his head.
23
24         I know. Oops! :/
25
26         So anyways, I am willing to sell you the body for $1 million dollars.
27
28         Be near the pinhole to the Dimension of Pain at midnight.
29
30         Alias
31
32         AMBUSH_READY
33
34         # 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

DESCRIPTION

43       The basics should all work, but this module is still subject to name
44       and/or API changes
45
46       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
51       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
56       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
60   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
65       (Actually, the choice of default is delegated to Email::Sender::Simple,
66       which makes its own choices.  But usually, it uses "sendmail".)
67
68   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
73       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
79       Then there's brevity... compare the following roughly equivalent code.
80
81       First, the Email::Stuffer way.
82
83         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
89       And now doing it directly with a knowledge of what your attachment is,
90       and what the correct MIME structure is.
91
92         use Email::MIME;
93         use Email::Sender::Simple;
94         use IO::All;
95
96         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
117       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
120       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

PERL VERSION

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
129       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

METHODS

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
139       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
143   new
144       Creates a new, empty, Email::Stuffer object.
145
146       You can pass a hashref of properties to set, including:
147
148       •   to
149
150       •   from
151
152       •   cc
153
154       •   bcc
155
156       •   reply_to
157
158       •   subject
159
160       •   text_body
161
162       •   html_body
163
164       •   transport
165
166       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
170   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
174   parts
175       Returns, as a list, the Email::MIME parts for the Email
176
177   header
178         $stuffer->header($header_name = $value)
179
180       This method sets a named header in the email. Multiple calls with the
181       same $header_name will overwrite previous calls $value.
182
183   to
184         $stuffer->to(@addresses)
185
186       This method sets the To header in the email.
187
188   from
189         $stuffer->from($address)
190
191       This method sets the From header in the email.
192
193   reply_to
194         $stuffer->reply_to($address)
195
196       This method sets the Reply-To header in the email.
197
198   cc
199         $stuffer->cc(@addresses)
200
201       This method sets the Cc header in the email.
202
203   bcc
204         $stuffer->bcc(@addresses)
205
206       This method sets the Bcc header in the email.
207
208   subject
209         $stuffer->subject($text)
210
211       This method sets the Subject header in the email.
212
213   text_body
214         $stuffer->text_body($body, %attributes);
215
216       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
220       If $body is undefined, this method will do nothing.
221
222       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
230   html_body
231         $stuffer->html_body($body, %attributes);
232
233       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
237       If $body is undefined, this method will do nothing.
238
239   attach
240         $stuffer->attach($contents, %attributes)
241
242       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
249   attach_file
250         $stuffer->attach_file($file, %attributes)
251
252       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
257       $file can be a filename or an IO::All::File object.
258
259   transport
260         $stuffer->transport( $moniker, @options )
261
262       or
263
264         $stuffer->transport( $transport_obj )
265
266       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
273       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
276   email
277         my $email_mime = $stuffer->email;
278
279       This method creates and returns the full Email::MIME object for the
280       email.
281
282   as_string
283         my $email_document = $stuffer->as_string;
284
285       Returns the string form of the email.  Identical to (and uses behind
286       the scenes) "Email::MIME->as_string".
287
288   send
289         $stuffer->send;
290
291       or
292
293         $stuffer->send({ to => [ $to_1, $to_2 ], from => $sender });
294
295       Sends the email via Email::Sender::Simple.  Envelope information can be
296       specified in a hash reference.
297
298       On failure, returns false.
299
300   send_or_die
301         $stuffer->send_or_die;
302
303       or
304
305         $stuffer->send_or_die({ to => [ $to_1, $to_2 ], from => $sender });
306
307       Sends the email via Email::Sender::Simple.  Envelope information can be
308       specified in a hash reference.
309
310       On failure, throws an exception.
311

COOKBOOK

313       Here is another example (maybe plural later) of how you can use
314       Email::Stuffer's brevity to your advantage.
315
316   Custom Alerts
317         package SMS::Alert;
318         use base 'Email::Stuffer';
319
320         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
329         package My::Code;
330
331         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

TO DO

339       •   Fix a number of bugs still likely to exist
340
341       •   Write more tests.
342
343       •   Add any additional small bit of automation that isn't too expensive
344

SEE ALSO

346       Email::MIME, Email::Sender, <http://ali.as/>
347

AUTHORS

349       •   Adam Kennedy <adamk@cpan.org>
350
351       •   Ricardo SIGNES <cpan@semiotic.systems>
352

CONTRIBUTORS

354       •   Aaron W. Swenson <aaron.w.swenson@gmail.com>
355
356       •   adam <adam@88f4d9cd-8a04-0410-9d60-8f63309c3137>
357
358       •   adamk@cpan.org
359           <adamk@cpan.org@88f4d9cd-8a04-0410-9d60-8f63309c3137>
360
361       •   adam@phase-n.com
362           <adam@phase-n.com@88f4d9cd-8a04-0410-9d60-8f63309c3137>
363
364       •   Alastair Douglas <altreus@altre.us>
365
366       •   Aristotle Pagaltzis <pagaltzis@gmx.de>
367
368       •   Chase Whitener <chase.whitener@infotechfl.com>
369
370       •   CosmicNet <webmaster@cosmicperl.com>
371
372       •   Dan Book <grinnz@gmail.com>
373
374       •   fREW Schmidt <frioux@gmail.com>
375
376       •   John Napiorkowski <jjn1056@yahoo.com>
377
378       •   Josh Stompro <github@stompro.org>
379
380       •   Kevin Tew <tewk@tan.tewk.com>
381
382       •   Kieren Diment <kd@fenchurch.local>
383
384       •   Kris Matthews <kris@tigerlms.com>
385
386       •   Lee Johnson <lee@givengain.ch>
387
388       •   Manni Heumann <github@lxxi.org>
389
390       •   Pali <pali@cpan.org>
391
392       •   Ricardo Signes <rjbs@semiotic.systems>
393
394       •   Ross Attrill <ross.attrill@gmail.com>
395
396       •   Russell Jenkins <russell.jenkins@strategicdata.com.au>
397
398       •   Shawn Sorichetti <shawn@coloredblocks.com>
399
400       •   Steve Dondley <s@dondley.com>
401
402       •   tokuhirom <tokuhirom@gmail.com>
403
405       This software is copyright (c) 2004 by Adam Kennedy and Ricardo SIGNES.
406
407       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.
409
410
411
412perl v5.38.0                      2023-07-20                 Email::Stuffer(3)
Impressum