Cataly...::Email(3pm)

💌 Catalyst::View::Email — the send-emails-from-Catalyst era 💌

okay bestie, so this is Catalyst::View::Email, straight outta the User Contributed Perl Documentation shelf (it's a 3pm page, iykyk) — and it does exactly one iconic thing: it sends emails from your Catalyst app. that's it, that's the vibe. 🦋

---

✨ NAME ✨

Catalyst::View::Email — Send Email from Catalyst. yes, literally that. it's giving "your app can send mail now". 💅

---

✨ SYNOPSIS ✨

so this module sends out emails from a stash key, and which key that is? that's in your configuration settings. that's the whole deal fr fr. 🌸

---

✨ CONFIGURATION ✨

WARNING: since version 0.10 the configuration options slightly changed! not me warning you about a breaking-ish change 💀 pay attention.

Use the helper to create your View:

$ script/myapp_create.pl view Email Email

In your app configuration:

__PACKAGE__->config(
    'View::Email' => {
        # Where to look in the stash for the email information.
        # 'email' is the default, so you don't have to specify it.
        stash_key => 'email',
        # Define the defaults for the mail
        default => {
            # Defines the default content type (mime type). Mandatory
            content_type => 'text/plain',
            # 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't be set for all MIME parts
            # without an overridden one.
            # Default: none
            charset => 'utf-8'
        },
        # Setup how to send the email
        # all those options are passed directly to Email::Sender::Simple
        sender => {
            # if mailer doesn't start with Email::Sender::Simple::Transport::,
            # then this is prepended.
            mailer => 'SMTP',
            # mailer_args is passed directly into Email::Sender::Simple
            mailer_args => {
                host     => 'smtp.example.com', # defaults to localhost
                sasl_username => 'sasl_username',
                sasl_password => 'sasl_password',
        }
      }
    }
);

a lil breakdown for my girlies, no gatekeeping:

• stash_key — where in the stash we go looking for the email info. 'email' is the default, so honestly you don't even have to write it. optional queen.
• default — the defaults for your mail.
  • content_type — the default content type (mime type). mandatory!! don't skip her.
  • charset — the default charset for every MIME part whose content type is text. per RFC2049, a MIME part with no charset should be treated as US-ASCII by the mail client. if the charset isn't set, it just won't be set for all the MIME parts that don't have their own overridden one. default: none.
• sender — how to actually send the thing. all those options get passed directly to Email::Sender::Simple.
  • mailer — if the mailer doesn't start with Email::Sender::Simple::Transport::, that gets prepended.
  • mailer_args — passed directly into Email::Sender::Simple. host defaults to localhost.

---

✨ NOTE ON SMTP ✨

If you use SMTP and don't specify host, it defaults to localhost and it will attempt delivery. and bestie, this often means an email will sit in a queue and not be delivered. the way that it just… sits there 💀

---

✨ SENDING EMAIL ✨

Sending email is just filling the stash and forwarding to the view. that's it. iconic behavior.

sub controller : Private {
    my ( $self, $c ) = @_;

    $c->stash->{email} = {
        to      => 'jshirley@gmail.com',
        cc      => 'abraxxa@cpan.org',
        from    => 'no-reply@foobar.com',
        subject => 'I am a Catalyst generated email',
        body    => 'Body Body Body',
    };

    $c->forward( $c->view('Email') );
}

🌈 the raw interface 🌈

Alternatively you can use a more raw interface and specify the headers as an array reference, exactly like it's passed to Email::MIME::Creator. note that you may also mix both syntaxes if you like ours better but you need to specify additional header attributes. the attributes get appended to the header array reference without overwriting the ones already in there. no clobbering, we don't do that here. 🙈

$c->stash->{email} = {
    header => [
        To      => 'jshirley@gmail.com',
        Cc      => 'abraxxa@cpan.org',
        Bcc     => join ',', qw/hidden@secret.com hidden2@foobar.com/,
        From    => 'no-reply@foobar.com',
        Subject => 'Note the capitalization differences',
    ],
    body => qq{Ain't got no body, and nobody cares.},
    # Or, send parts
    parts => [
        Email::MIME->create(
            attributes => {
                content_type => 'text/plain',
                disposition  => 'attachment',
                charset      => 'US-ASCII',
            },
            body => qq{Got a body, but didn't get ahead.},
        )
    ],
};

🌈 envelope sender + recipient 🌈

You can set the envelope sender and recipient as well:

$c->stash->{email} = {

  envelope_from => 'envelope-from@example.com',
  from          => 'header-from@example.com',

  envelope_to   => [ 'foo@example.com', 'bar@example.com' ],
  to            => 'Undisclosed Recipients:;',

  ...
};

---

✨ HANDLING ERRORS ✨

If the email fails to send, the view will die (throw an exception). so after your forward to the view, it is a good idea to check for errors:

$c->forward( $c->view('Email') );

if ( scalar( @{ $c->error } ) ) {
    $c->error(0); # Reset the error condition if you need to
    $c->response->body('Oh noes!');
} else {
    $c->response->body('Email sent A-OK! (At least as far as we can tell)');
}

"at least as far as we can tell" is such a mood honestly 😭

---

✨ 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. fancy mail era unlocked ✨

---

✨ METHODS ✨

• new — Validates the base config and creates the Email::Sender::Simple object for later use by process.
• process($c) — The process method does the actual processing when the view is dispatched to. This method sets up the email parts and hands off to Email::Sender::Simple to handle the actual email delivery. the main character of methods tbh.
• 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 "attributes" key.
• generate_message($c, $attr) — Generate a message part, which should be an Email::MIME object, and return it. Takes the attributes, merges with the defaults as necessary, and returns a message object.

---

✨ TROUBLESHOOTING ✨

As with most things computer related, things break. Email even more so. 😭 typically any errors are going to come from using SMTP 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.

If you are using SMTP and have troubles sending — whether it is authentication or a very bland "Can't send" message — make sure that you have Net::SMTP and, if applicable, Net::SMTP::SSL installed.

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! manifest it ✨

---

✨ SEE ALSO ✨

• Catalyst::View::Email::Template — Send fancy template emails with Cat
• Catalyst::Manual — The Catalyst Manual
• Catalyst::Manual::Cookbook — The Catalyst Cookbook

---

✨ AUTHORS ✨

• J. Shirley <jshirley@gmail.com>
• Alexander Hartmaier <abraxxa@cpan.org>

---

✨ CONTRIBUTORS ✨

(Thanks!) 🫶

• Matt S Trout
• Daniel Westermann-Clark
• Simon Elliott <cpan@browsing.co.uk>
• Roman Filippov
• Lance Brown <lance@bearcircle.net>
• Devin Austin <dhoss@cpan.org>
• Chris Nehren <apeiron@cpan.org>

---

✨ COPYRIGHT ✨

Copyright (c) 2007 - 2009 the Catalyst::View::Email "AUTHORS" and "CONTRIBUTORS" as listed above.

---

✨ LICENSE ✨

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself. slay, open source. 💜

---

and that's the whole page bestie!! this is perl v5.38.2, dated 2024-03-04 — so if you're reading this, that's the version + date energy you're working with. go forth and send some mail, you got this 👑💖