.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Catalyst::View::Email 3pm" .TH Catalyst::View::Email 3pm "2015-09-25" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Catalyst::View::Email \- Send Email from Catalyst .SH "SYNOPSIS" .IX Header "SYNOPSIS" This module sends out emails from a stash key specified in the configuration settings. .SH "CONFIGURATION" .IX Header "CONFIGURATION" \&\s-1WARNING:\s0 since version 0.10 the configuration options slightly changed! .PP Use the helper to create your View: .PP .Vb 1 \& $ script/myapp_create.pl view Email Email .Ve .PP In your app configuration: .PP .Vb 10 \& _\|_PACKAGE_\|_\->config( \& \*(AqView::Email\*(Aq => { \& # Where to look in the stash for the email information. \& # \*(Aqemail\*(Aq is the default, so you don\*(Aqt have to specify it. \& stash_key => \*(Aqemail\*(Aq, \& # Define the defaults for the mail \& default => { \& # Defines the default content type (mime type). Mandatory \& content_type => \*(Aqtext/plain\*(Aq, \& # Defines the default charset for every MIME part with the \& # content type text. \& # According to RFC2049 a MIME part without a charset should \& # be treated as US\-ASCII by the mail client. \& # If the charset is not set it won\*(Aqt be set for all MIME parts \& # without an overridden one. \& # Default: none \& charset => \*(Aqutf\-8\*(Aq \& }, \& # Setup how to send the email \& # all those options are passed directly to Email::Sender::Simple \& sender => { \& # if mailer doesn\*(Aqt start with Email::Sender::Simple::Transport::, \& # then this is prepended. \& mailer => \*(AqSMTP\*(Aq, \& # mailer_args is passed directly into Email::Sender::Simple \& mailer_args => { \& host => \*(Aqsmtp.example.com\*(Aq, # defaults to localhost \& sasl_username => \*(Aqsasl_username\*(Aq, \& sasl_password => \*(Aqsasl_password\*(Aq, \& } \& } \& } \& ); .Ve .SH "NOTE ON SMTP" .IX Header "NOTE ON SMTP" If you use \s-1SMTP\s0 and don't specify host, it will default to localhost and attempt delivery. This often means an email will sit in a queue and not be delivered. .SH "SENDING EMAIL" .IX Header "SENDING EMAIL" Sending email is just filling the stash and forwarding to the view: .PP .Vb 2 \& sub controller : Private { \& my ( $self, $c ) = @_; \& \& $c\->stash\->{email} = { \& to => \*(Aqjshirley@gmail.com\*(Aq, \& cc => \*(Aqabraxxa@cpan.org\*(Aq, \& from => \*(Aqno\-reply@foobar.com\*(Aq, \& subject => \*(AqI am a Catalyst generated email\*(Aq, \& body => \*(AqBody Body Body\*(Aq, \& }; \& \& $c\->forward( $c\->view(\*(AqEmail\*(Aq) ); \& } .Ve .PP Alternatively you can use a more raw interface and specify the headers as an array reference like it is passed to Email::MIME::Creator. Note that you may also mix both syntaxes if you like ours better but need to specify additional header attributes. The attributes are appended to the header array reference without overwriting contained ones. .PP .Vb 10 \& $c\->stash\->{email} = { \& header => [ \& To => \*(Aqjshirley@gmail.com\*(Aq, \& Cc => \*(Aqabraxxa@cpan.org\*(Aq, \& Bcc => join \*(Aq,\*(Aq, qw/hidden@secret.com hidden2@foobar.com/, \& From => \*(Aqno\-reply@foobar.com\*(Aq, \& Subject => \*(AqNote the capitalization differences\*(Aq, \& ], \& body => qq{Ain\*(Aqt got no body, and nobody cares.}, \& # Or, send parts \& parts => [ \& Email::MIME\->create( \& attributes => { \& content_type => \*(Aqtext/plain\*(Aq, \& disposition => \*(Aqattachment\*(Aq, \& charset => \*(AqUS\-ASCII\*(Aq, \& }, \& body => qq{Got a body, but didn\*(Aqt get ahead.}, \& ) \& ], \& }; .Ve .PP You can set the envelope sender and recipient as well: .PP .Vb 1 \& $c\->stash\->{email} = { \& \& envelope_from => \*(Aqenvelope\-from@example.com\*(Aq, \& from => \*(Aqheader\-from@example.com\*(Aq, \& \& envelope_to => [ \*(Aqfoo@example.com\*(Aq, \*(Aqbar@example.com\*(Aq ], \& to => \*(AqUndisclosed Recipients:;\*(Aq, \& \& ... \& }; .Ve .SH "HANDLING ERRORS" .IX Header "HANDLING ERRORS" If the email fails to send, the view will die (throw an exception). After your forward to the view, it is a good idea to check for errors: .PP .Vb 1 \& $c\->forward( $c\->view(\*(AqEmail\*(Aq) ); \& \& if ( scalar( @{ $c\->error } ) ) { \& $c\->error(0); # Reset the error condition if you need to \& $c\->response\->body(\*(AqOh noes!\*(Aq); \& } else { \& $c\->response\->body(\*(AqEmail sent A\-OK! (At least as far as we can tell)\*(Aq); \& } .Ve .SH "USING TEMPLATES FOR EMAIL" .IX Header "USING TEMPLATES FOR EMAIL" Now, it's no fun to just send out email using plain strings. Take a look at Catalyst::View::Email::Template to see how you can use your favourite template engine to render the mail body. .SH "METHODS" .IX Header "METHODS" .IP "new" 4 .IX Item "new" Validates the base config and creates the Email::Sender::Simple object for later use by process. .IP "process($c)" 4 .IX Item "process($c)" The process method does the actual processing when the view is dispatched to. .Sp This method sets up the email parts and hands off to Email::Sender::Simple to handle the actual email delivery. .ie n .IP "setup_attributes($c, $attr)" 4 .el .IP "setup_attributes($c, \f(CW$attr\fR)" 4 .IX Item "setup_attributes($c, $attr)" Merge attributes with the configured defaults. You can override this method to return a structure to pass into generate_message which subsequently passes the return value of this method to Email::MIME\->create under the \&\f(CW\*(C`attributes\*(C'\fR key. .ie n .IP "generate_message($c, $attr)" 4 .el .IP "generate_message($c, \f(CW$attr\fR)" 4 .IX Item "generate_message($c, $attr)" Generate a message part, which should be an Email::MIME object and return it. .Sp Takes the attributes, merges with the defaults as necessary and returns a message object. .SH "TROUBLESHOOTING" .IX Header "TROUBLESHOOTING" As with most things computer related, things break. Email even more so. Typically any errors are going to come from using \s-1SMTP\s0 as your sending method, which means that if you are having trouble the first place to look is at Email::Sender::Transport::SMTP. This module is just a wrapper for Email::Sender::Simple, so if you get an error on sending, it is likely from there anyway. .PP If you are using \s-1SMTP\s0 and have troubles sending, whether it is authentication or a very bland \*(L"Can't send\*(R" message, make sure that you have Net::SMTP and, if applicable, Net::SMTP::SSL installed. .PP It is very simple to check that you can connect via Net::SMTP, and if you do have sending errors the first thing to do is to write a simple script that attempts to connect. If it works, it is probably something in your configuration so double check there. If it doesn't, well, keep modifying the script and/or your mail server configuration until it does! .SH "SEE ALSO" .IX Header "SEE ALSO" .SS "Catalyst::View::Email::Template \- Send fancy template emails with Cat" .IX Subsection "Catalyst::View::Email::Template - Send fancy template emails with Cat" .SS "Catalyst::Manual \- The Catalyst Manual" .IX Subsection "Catalyst::Manual - The Catalyst Manual" .SS "Catalyst::Manual::Cookbook \- The Catalyst Cookbook" .IX Subsection "Catalyst::Manual::Cookbook - The Catalyst Cookbook" .SH "AUTHORS" .IX Header "AUTHORS" J. Shirley .PP Alexander Hartmaier .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" (Thanks!) .PP Matt S Trout .PP Daniel Westermann-Clark .PP Simon Elliott .PP Roman Filippov .PP Lance Brown .PP Devin Austin .PP Chris Nehren .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2007 \- 2009 the Catalyst::View::Email \*(L"\s-1AUTHORS\*(R"\s0 and \*(L"\s-1CONTRIBUTORS\*(R"\s0 as listed above. .SH "LICENSE" .IX Header "LICENSE" This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.