1
2=encoding UTF-8
3
4=head1 NAME
5
6Mojolicious::Plugin::Mail - Mojolicious Plugin for send mail
7
8=head1 SYNOPSIS
9
10 # Mojolicious::Lite
11 plugin 'mail';
12
13 # Mojolicious with config
14 $self->plugin(mail => {
15 from => 'sharifulin@gmail.com',
16 type => 'text/html',
17 });
18
19 # in controller
20 $self->mail(
21 to => 'sharifulin@gmail.com',
22 subject => 'Test',
23 data => 'use Perl or die;',
24 );
25
26 # in controller, using render
27 $self->mail(to => 'sharifulin@gmail.com', template => 'controller/action', format => 'mail');
28
29 # template: controller/action.mail.ep
30 % stash subject => 'Test';
31 use Perl or die;
32
33
34=head1 DESCRIPTION
35
36L<Mojolicous::Plugin::Mail> is a plugin for Mojolicious apps to send mail using L<MIME::Lite>.
37Mojolicious 4.0 ready.
38
39=head1 HELPERS
40
41L<Mojolicious::Plugin::Mail> contains two helpers: I<mail> and I<render_mail>.
42
43=head2 C<mail>
44
45 # simple interface
46 $self->mail(
47 to => 'sharifulin@gmail.com',
48 from => 'sharifulin@gmail.com',
49
50 reply_to => 'reply_to+sharifulin@gmail.com',
51
52 cc => '..',
53 bcc => '..',
54
55 type => 'text/plain',
56
57 subject => 'Test',
58 data => 'use Perl or die;',
59 );
60
61 # interface as MIME::Lite
62 $self->mail(
63 # test mode
64 test => 1,
65
66 # as MIME::Lite->new( ... )
67 mail => {
68 To => 'sharifulin@gmail.com',
69 Subject => 'Test',
70 Data => 'use Perl or die;',
71 },
72
73 attach => [
74 # as MIME::Lite->attach( .. )
75 { ... },
76 ...
77 },
78
79 headers => [
80 # as MIME::Lite->add( .. )
81 { ... },
82 ...
83 },
84
85 attr => [
86 # as MIME::Lite->attr( .. )
87 { ... },
88 ...
89 },
90 );
91
92Build and send email, return mail as string.
93
94Supported parameters:
95
96=over 16
97
98=item * to
99
100Header 'To' of mail.
101
102=item * from
103
104Header 'From' of mail.
105
106=item * reply_to
107
108Header 'Reply-To' of mail.
109
110=item * cc
111
112Header 'Cc' of mail.
113
114=item * bcc
115
116Header 'Bcc' of mail.
117
118=item * type
119
120Content type of mail, default is conf's type.
121
122=item * subject
123
124Header 'Subject' of mail.
125
126=item * data
127
128Content of mail
129
130=item * mail
131
132Hashref, containts parameters as I<new(PARAMHASH)>. See L<MIME::Lite>.
133
134=item * attach
135
136Arrayref of hashref, hashref containts parameters as I<attach(PARAMHASH)>. See L<MIME::Lite>.
137
138=item * headers
139
140Arrayref of hashref, hashref containts parameters as I<add(TAG, VALUE)>. See L<MIME::Lite>.
141
142=item * attr
143
144Arrayref of hashref, hashref containts parameters as I<attr(ATTR, VALUE)>. See L<MIME::Lite>.
145
146=item * test
147
148Test mode, don't send mail.
149
150=item * charset
151
152Charset of mail, default charset is UTF-8.
153
154=item * mimeword
155
156Using mimeword or not, default value is 1.
157
158=item * nomailer
159
160No using 'X-Mailer' header of mail, default value is 1.
161
162=back
163
164If no subject, uses value of stash parameter 'subject'.
165
166If no data, call I<render_mail> helper with all stash parameters.
167
168=head2 C<render_mail>
169
170 my $data = $self->render_mail('user/signup');
171
172 # or use stash params
173 my $data = $self->render_mail(template => 'user/signup', user => $user);
174
175Render mail template and return data, mail template format is I<mail>, i.e. I<user/signup.mail.ep>.
176
177=head1 ATTRIBUTES
178
179L<Mojolicious::Plugin::Mail> contains one attribute - conf.
180
181=head2 C<conf>
182
183 $plugin->conf;
184
185Config of mail plugin, hashref.
186
187Keys of conf:
188
189=over 6
190
191=item * from
192
193From address, default value is I<test-mail-plugin@mojolicio.us>.
194
195=item * encoding
196
197Encoding of Subject and any Data, value is MIME::Lite content transfer encoding L<http://search.cpan.org/~rjbs/MIME-Lite-3.027/lib/MIME/Lite.pm#Content_transfer_encodings>
198Default value is I<base64>.
199
200=item * charset
201
202Default charset of Subject and any Data, default value is I<UTF-8>.
203
204=item * type
205
206Default type of Data, default value is I<text/plain>.
207
208=item * how
209
210HOW parameter of MIME::Lite::send: I<sendmail> or I<smtp>.
211
212=item * howargs
213
214HOWARGS parameter of MIME::Lite::send (arrayref).
215
216=back
217
218 my $conf = {
219 from => 'sharifulin@gmail.com,
220 encoding => 'base64',
221 type => 'text/html',
222 how => 'sendmail',
223 howargs => [ '/usr/sbin/sendmail -t' ],
224 };
225
226 # in Mojolicious app
227 $self->plugin(mail => $conf);
228
229 # in Mojolicious::Lite app
230 plugin mail => $conf;
231
232
233=head1 METHODS
234
235L<Mojolicious::Plugin::Mail> inherits all methods from
236L<Mojolicious::Plugin> and implements the following new ones.
237
238=head2 C<register>
239
240 $plugin->register($app, $conf);
241
242Register plugin hooks in L<Mojolicious> application.
243
244=head2 C<build>
245
246 $plugin->build( mail => { ... }, ... );
247
248Build mail using L<MIME::Lite> and L<MIME::EncWords> and return MIME::Lite object.
249
250=head1 TEST MODE
251
252L<Mojolicious::Plugin::Mail> has test mode, no send mail.
253
254 # all mail don't send mail
255 BEGIN { $ENV{MOJO_MAIL_TEST} = 1 };
256
257 # or only once
258 $self->mail(
259 test => 1,
260 to => '...',
261 );
262
263=head1 EXAMPLES
264
265The Mojolicious::Lite example you can see in I<example/test.pl>.
266
267Simple interface for send plain mail:
268
269 get '/simple' => sub {
270 my $self = shift;
271
272 $self->mail(
273 to => 'sharifulin@gmail.com',
274 type => 'text/plain',
275 subject => 'Тест письмо',
276 data => 'Привет!',
277 );
278 };
279
280Simple send mail:
281
282 get '/simple' => sub {
283 my $self = shift;
284
285 $self->mail(
286 mail => {
287 To => 'sharifulin@gmail.com',
288 Subject => 'Тест письмо',
289 Data => "<p>Привет!</p>",
290 },
291 );
292 };
293
294Simple send mail with test mode:
295
296 get '/simple2' => sub {
297 my $self = shift;
298
299 my $mail = $self->mail(
300 test => 1,
301 mail => {
302 To => '"Анатолий Шарифулин" sharifulin@gmail.com',
303 Cc => '"Анатолий Шарифулин" <sharifulin@gmail.com>, Anatoly Sharifulin sharifulin@gmail.com',
304 Bcc => 'sharifulin@gmail.com',
305 Subject => 'Тест письмо',
306 Type => 'text/plain',
307 Data => "<p>Привет!</p>",
308 },
309 );
310
311 warn $mail;
312 };
313
314Mail with binary attachcment, charset is windows-1251, mimewords off and mail has custom header:
315
316 get '/attach' => sub {
317 my $self = shift;
318
319 my $mail = $self->mail(
320 charset => 'windows-1251',
321 mimeword => 0,
322
323 mail => {
324 To => 'sharifulin@gmail.com',
325 Subject => 'Test attach',
326 Type => 'multipart/mixed'
327 },
328 attach => [
329 {
330 Data => 'Any data',
331 },
332 {
333 Type => 'BINARY',
334 Filename => 'crash.data',
335 Disposition => 'attachment',
336 Data => 'binary data binary data binary data binary data binary data',
337 },
338 ],
339 headers => [ { 'X-My-Header' => 'Mojolicious' } ],
340 );
341 };
342
343Multipart mixed mail:
344
345 get '/multi' => sub {
346 my $self = shift;
347
348 $self->mail(
349 mail => {
350 To => 'sharifulin@gmail.com',
351 Subject => 'Мульти',
352 Type => 'multipart/mixed'
353 },
354
355 attach => [
356 {
357 Type => 'TEXT',
358 Encoding => '7bit',
359 Data => "Just a quick note to say hi!"
360 },
361 {
362 Type => 'image/gif',
363 Path => $0
364 },
365 {
366 Type => 'x-gzip',
367 Path => "gzip < $0 |",
368 ReadNow => 1,
369 Filename => "somefile.zip"
370 },
371 ],
372 );
373 };
374
375Render mail using simple interface and Reply-To header:
376
377 get '/render_simple' => sub {
378 my $self = shift;
379 my $mail = $self->mail(to => 'sharifulin@gmail.com', reply_to => 'reply_to+sharifulin@gmail.com');
380
381 $self->render(ok => 1, mail => $mail);
382} => 'render';
383
384Mail with render data and subject from stash param:
385
386 get '/render' => sub {
387 my $self = shift;
388
389 my $data = $self->render_mail('render');
390 $self->mail(
391 mail => {
392 To => 'sharifulin@gmail.com',
393 Subject => $self->stash('subject'),
394 Data => $data,
395 },
396 );
397 } => 'render';
398
399 __DATA__
400
401 @@ render.html.ep
402 <p>Hello render!</p>
403
404 @@ render.mail.ep
405 % stash 'subject' => 'Привет render';
406
407 <p>Привет mail render!</p>
408
409=head1 SEE ALSO
410
411L<MIME::Lite> L<MIME::EncWords> L<Mojolicious> L<Mojolicious::Guides> L<http://mojolicious.org>.
412
413=head1 AUTHOR
414
415Anatoly Sharifulin <sharifulin@gmail.com>
416
417=head1 THANKS
418
419Alex Kapranoff <kapranoff@gmail.com>
420
421=head1 BUGS
422
423Please report any bugs or feature requests to C<bug-mojolicious-plugin-mail at rt.cpan.org>, or through
424the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.htMail?Queue=Mojolicious-Plugin-Mail>. We will be notified, and then you'll
425automatically be notified of progress on your bug as we make changes.
426
427=over 5
428
429=item * Github
430
431L<http://github.com/sharifulin/mojolicious-plugin-mail/tree/master>
432
433=item * RT: CPAN's request tracker
434
435L<http://rt.cpan.org/NoAuth/Bugs.htMail?Dist=Mojolicious-Plugin-Mail>
436
437=item * AnnoCPAN: Annotated CPAN documentation
438
439L<http://annocpan.org/dist/Mojolicious-Plugin-Mail>
440
441=item * CPANTS: CPAN Testing Service
442
443L<http://cpants.perl.org/dist/overview/Mojolicious-Plugin-Mail>
444
445=item * CPAN Ratings
446
447L<http://cpanratings.perl.org/d/Mojolicious-Plugin-Mail>
448
449=item * Search CPAN
450
451L<http://search.cpan.org/dist/Mojolicious-Plugin-Mail>
452
453=back
454
455=head1 COPYRIGHT & LICENSE
456
457Copyright (C) 2010-2015 by Anatoly Sharifulin.
458
459This program is free software; you can redistribute it and/or modify it
460under the same terms as Perl itself.
461
462=cut
463