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.018
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

METHODS

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
130       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
134   new
135       Creates a new, empty, Email::Stuffer object.
136
137       You can pass a hashref of properties to set, including:
138
139       •   to
140
141       •   from
142
143       •   cc
144
145       •   bcc
146
147       •   reply_to
148
149       •   subject
150
151       •   text_body
152
153       •   html_body
154
155       •   transport
156
157       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
161   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
165   parts
166       Returns, as a list, the Email::MIME parts for the Email
167
168   header $header => $value
169       Sets a named header in the email. Multiple calls with the same $header
170       will overwrite previous calls $value.
171
172   to @addresses
173       Sets the To: header in the email
174
175   from $address
176       Sets the From: header in the email
177
178   reply_to $address
179       Sets the Reply-To: header in the email
180
181   cc @addresses
182       Sets the Cc: header in the email
183
184   bcc @addresses
185       Sets the Bcc: header in the email
186
187   subject $text
188       Sets the Subject: header in the email
189
190   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
195       If $body is undefined, this method will do nothing.
196
197       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
205   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
210       If $body is undefined, this method will do nothing.
211
212   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
220   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
226   transport
227         $stuffer->transport( $moniker, @options )
228
229       or
230
231         $stuffer->transport( $transport_obj )
232
233       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
240       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
243   email
244       Creates and returns the full Email::MIME object for the email.
245
246   as_string
247       Returns the string form of the email. Identical to (and uses behind the
248       scenes) Email::MIME->as_string.
249
250   send
251         $stuffer->send;
252
253       or
254
255         $stuffer->send({ to => [ $to_1, $to_2 ], from => $sender });
256
257       Sends the email via Email::Sender::Simple.  Envelope information can be
258       specified in a hash reference.
259
260       On failure, returns false.
261
262   send_or_die
263         $stuffer->send_or_die;
264
265       or
266
267         $stuffer->send_or_die({ to => [ $to_1, $to_2 ], from => $sender });
268
269       Sends the email via Email::Sender::Simple.  Envelope information can be
270       specified in a hash reference.
271
272       On failure, throws an exception.
273

COOKBOOK

275       Here is another example (maybe plural later) of how you can use
276       Email::Stuffer's brevity to your advantage.
277
278   Custom Alerts
279         package SMS::Alert;
280         use base 'Email::Stuffer';
281
282         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
291         package My::Code;
292
293         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

TO DO

301       •   Fix a number of bugs still likely to exist
302
303       •   Write more tests.
304
305       •   Add any additional small bit of automation that isn't too expensive
306

SEE ALSO

308       Email::MIME, Email::Sender, <http://ali.as/>
309

AUTHORS

311       •   Adam Kennedy <adamk@cpan.org>
312
313       •   Ricardo SIGNES <rjbs@cpan.org>
314

CONTRIBUTORS

316       •   Aaron W. Swenson <aaron.w.swenson@gmail.com>
317
318       •   adam <adam@88f4d9cd-8a04-0410-9d60-8f63309c3137>
319
320       •   adamk@cpan.org
321           <adamk@cpan.org@88f4d9cd-8a04-0410-9d60-8f63309c3137>
322
323       •   adam@phase-n.com
324           <adam@phase-n.com@88f4d9cd-8a04-0410-9d60-8f63309c3137>
325
326       •   Alastair Douglas <altreus@altre.us>
327
328       •   Aristotle Pagaltzis <pagaltzis@gmx.de>
329
330       •   Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
331
332       •   Chase Whitener <chase.whitener@infotechfl.com>
333
334       •   CosmicNet <webmaster@cosmicperl.com>
335
336       •   Dan Book <grinnz@gmail.com>
337
338       •   John Napiorkowski <jjn1056@yahoo.com>
339
340       •   Josh Stompro <github@stompro.org>
341
342       •   Kevin Tew <tewk@tan.tewk.com>
343
344       •   Kieren Diment <kd@fenchurch.local>
345
346       •   Kris Matthews <krismatth@icloud.com>
347
348       •   Kris Matthews <kris@tigerlms.com>
349
350       •   Lee Johnson <lee@givengain.ch>
351
352       •   Manni Heumann <github@lxxi.org>
353
354       •   Pali <pali@cpan.org>
355
356       •   Ricardo Signes <rjbs@semiotic.systems>
357
358       •   Ross Attrill <ross.attrill@gmail.com>
359
360       •   Russell Jenkins <russell.jenkins@strategicdata.com.au>
361
362       •   Shawn Sorichetti <shawn@coloredblocks.com>
363
364       •   Steve Dondley <s@dondley.com>
365
366       •   tokuhirom <tokuhirom@gmail.com>
367
369       This software is copyright (c) 2004 by Adam Kennedy and Ricardo SIGNES.
370
371       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.
373
374
375
376perl v5.34.0                      2021-07-22                 Email::Stuffer(3)
Impressum