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.017
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 [, $attribuet => $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       Sends the email via Email::Sender::Simple.
252
253       On failure, returns false.
254
255   send_or_die
256       Sends the email via Email::Sender::Simple.
257
258       On failure, throws an exception.
259

COOKBOOK

261       Here is another example (maybe plural later) of how you can use
262       Email::Stuffer's brevity to your advantage.
263
264   Custom Alerts
265         package SMS::Alert;
266         use base 'Email::Stuffer';
267
268         sub new {
269           shift()->SUPER::new(@_)
270                  ->from('monitor@my.website')
271                  # Of course, we could have pulled these from
272                  # $MyConfig->{support_tech} or something similar.
273                  ->to('0416181595@sms.gateway')
274                  ->transport('SMTP', { host => '123.123.123.123' });
275         }
276
277         package My::Code;
278
279         unless ( $Server->restart ) {
280                 # Notify the admin on call that a server went down and failed
281                 # to restart.
282                 SMS::Alert->subject("Server $Server failed to restart cleanly")
283                           ->send;
284         }
285

TO DO

287       ·   Fix a number of bugs still likely to exist
288
289       ·   Write more tests.
290
291       ·   Add any additional small bit of automation that isn't too expensive
292

SEE ALSO

294       Email::MIME, Email::Sender, <http://ali.as/>
295

AUTHORS

297       ·   Adam Kennedy <adamk@cpan.org>
298
299       ·   Ricardo SIGNES <rjbs@cpan.org>
300

CONTRIBUTORS

302       ·   Aaron W. Swenson <aaron.w.swenson@gmail.com>
303
304       ·   adam <adam@88f4d9cd-8a04-0410-9d60-8f63309c3137>
305
306       ·   adamk@cpan.org
307           <adamk@cpan.org@88f4d9cd-8a04-0410-9d60-8f63309c3137>
308
309       ·   adam@phase-n.com
310           <adam@phase-n.com@88f4d9cd-8a04-0410-9d60-8f63309c3137>
311
312       ·   Aristotle Pagaltzis <pagaltzis@gmx.de>
313
314       ·   Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
315
316       ·   Chase Whitener <chase.whitener@infotechfl.com>
317
318       ·   CosmicNet <webmaster@cosmicperl.com>
319
320       ·   Dan Book <grinnz@gmail.com>
321
322       ·   John Napiorkowski <jjn1056@yahoo.com>
323
324       ·   Josh Stompro <github@stompro.org>
325
326       ·   Kevin Tew <tewk@tan.tewk.com>
327
328       ·   Kieren Diment <kd@fenchurch.local>
329
330       ·   Kris Matthews <krismatth@icloud.com>
331
332       ·   Kris Matthews <kris@tigerlms.com>
333
334       ·   Lee Johnson <lee@givengain.ch>
335
336       ·   Manni Heumann <github@lxxi.org>
337
338       ·   Pali <pali@cpan.org>
339
340       ·   Ross Attrill <ross.attrill@gmail.com>
341
342       ·   Shawn Sorichetti <shawn@coloredblocks.com>
343
344       ·   tokuhirom <tokuhirom@gmail.com>
345
347       This software is copyright (c) 2004 by Adam Kennedy and Ricardo SIGNES.
348
349       This is free software; you can redistribute it and/or modify it under
350       the same terms as the Perl 5 programming language system itself.
351
352
353
354perl v5.30.1                      2020-01-29                 Email::Stuffer(3)
Impressum