Commit | Line | Data |
5a5a0df4 |
1 | package Catalyst::Plugin::Email; |
2 | |
3 | use strict; |
4 | use Email::Send; |
5 | use Email::MIME; |
6 | use Email::MIME::Creator; |
7 | |
0da82223 |
8 | our $VERSION = '0.06'; |
5a5a0df4 |
9 | |
10 | =head1 NAME |
11 | |
12 | Catalyst::Plugin::Email - Send emails with Catalyst |
13 | |
14 | =head1 SYNOPSIS |
15 | |
16 | use Catalyst 'Email'; |
17 | |
18 | __PACKAGE__->config->{email} = [qw/SMTP smtp.oook.de/]; |
19 | |
20 | $c->email( |
21 | header => [ |
22 | From => 'sri@oook.de', |
23 | To => 'sri@cpan.org', |
24 | Subject => 'Hello!' |
25 | ], |
26 | body => 'Hello sri' |
27 | ); |
28 | |
29 | =head1 DESCRIPTION |
30 | |
31 | Send emails with Catalyst and L<Email::Send> and L<Email::MIME::Creator>. |
32 | |
0da82223 |
33 | =head1 CONFIGURATION |
34 | |
35 | C<config> accepts the same options as L<Email::Send>. |
36 | |
37 | To send using the system's C<sendmail> program, set C<config> like so: |
38 | |
39 | __PACKAGE__->config->{email} = ['Sendmail']; |
40 | |
41 | To send using authenticated SMTP: |
42 | |
43 | __PACKAGE__->config->{email} = [ |
44 | 'SMTP', |
45 | 'smtp.myhost.com', |
46 | username => $USERNAME, |
47 | password => $PASSWORD, |
48 | ]; |
49 | |
50 | For different methods of sending emails, and appropriate C<config> options, |
51 | see L<Email::Send::NNTP>, L<Email::Send::Qmail>, L<Email::Send::SMTP> and |
52 | L<Email::Send::Sendmail>. |
53 | |
54 | =head1 METHODS |
55 | |
56 | =head2 email |
57 | |
58 | C<email()> accepts the same arguments as L<Email::MIME::Creator>'s |
59 | C<create()>. |
60 | |
61 | $c->email( |
62 | header => [ |
63 | To => 'me@localhost', |
64 | Subject => 'A TT Email', |
65 | ], |
66 | body => $c->subreq( '/render_email' ), |
67 | ); |
68 | |
69 | To send a multipart message, include a C<parts> argument containing an |
70 | arrayref of Email::MIME objects. |
71 | |
72 | my @parts = ( |
73 | Email::MIME->create( |
74 | attributes => { |
75 | content_type => 'application/pdf', |
76 | encoding => 'quoted-printable', |
77 | name => 'report.pdf', |
78 | }, |
79 | body => $FILE_DATA, |
80 | ), |
81 | Email::MIME->create( |
82 | attributes => { |
83 | content_type => 'text/plain', |
84 | disposition => 'attachment', |
85 | charset => 'US-ASCII', |
86 | }, |
87 | body => $c->subreq( '/render_email' ), |
88 | ), |
89 | ); |
90 | |
91 | $c->email( |
92 | header => [ |
93 | To => 'me@localhost', |
94 | Subject => 'A TT Email', |
95 | ], |
96 | parts => \@parts, |
97 | ); |
98 | |
99 | =cut |
100 | |
101 | sub email { |
102 | my $c = shift; |
103 | my $email = $_[1] ? {@_} : $_[0]; |
104 | $email = Email::MIME->create(%$email); |
105 | my $args = $c->config->{email} || []; |
106 | my @args = @{$args}; |
107 | my $class; |
108 | unless ( $class = shift @args ) { |
109 | $class = 'SMTP'; |
110 | unshift @args, 'localhost'; |
111 | } |
112 | send $class => $email, @args; |
113 | } |
114 | |
95b3de58 |
115 | =head1 USING WITH A VIEW |
5a5a0df4 |
116 | |
95b3de58 |
117 | A common practice is to handle emails using the same template language used |
118 | for HTML pages. This can be accomplished by pairing this plugin with |
119 | L<Catalyst::Plugin::SubRequest>. |
120 | |
121 | Here is a short example of rendering an email from a Template Toolkit source |
122 | file. The call to $c->subreq makes an internal call to the render_email |
123 | method just like an external call from a browser. The request will pass |
124 | through the end method to be processed by your View class. |
125 | |
126 | sub send_email : Local { |
127 | my ( $self, $c ) = @_; |
128 | |
129 | $c->email( |
130 | header => [ |
131 | To => 'me@localhost', |
132 | Subject => 'A TT Email', |
133 | ], |
134 | body => $c->subreq( '/render_email' ), |
135 | ); |
136 | # redirect or display a message |
137 | } |
138 | |
139 | sub render_email : Local { |
140 | my ( $self, $c ) = @_; |
141 | |
142 | $c->stash( |
143 | names => [ qw/andyg sri mst/ ], |
144 | template => 'email.tt', |
145 | ); |
146 | } |
147 | |
148 | And the template: |
149 | |
150 | [%- FOREACH name IN names -%] |
151 | Hi, [% name %]! |
152 | [%- END -%] |
153 | |
154 | -- |
155 | Regards, |
156 | Us |
157 | |
158 | Output: |
159 | |
160 | Hi, andyg! |
161 | Hi, sri! |
162 | Hi, mst! |
163 | |
164 | -- |
165 | Regards, |
166 | Us |
167 | |
5a5a0df4 |
168 | =head1 SEE ALSO |
169 | |
95b3de58 |
170 | L<Catalyst>, L<Catalyst::Plugin::SubRequest>, L<Email::Send>, |
171 | L<Email::MIME::Creator> |
5a5a0df4 |
172 | |
173 | =head1 AUTHOR |
174 | |
175 | Sebastian Riedel, C<sri@cpan.org> |
176 | |
0da82223 |
177 | =head1 THANKS |
178 | |
179 | Andy Grundman - Additional documentation |
180 | |
181 | Carl Franks - Additional documentation |
182 | |
5a5a0df4 |
183 | =head1 COPYRIGHT |
184 | |
1ab6815b |
185 | This program is free software, you can redistribute it and/or modify it |
186 | under the same terms as Perl itself. |
5a5a0df4 |
187 | |
188 | =cut |
189 | |
190 | 1; |