Provided by: libcourriel-perl_0.45-1_all bug

NAME

       Courriel::Builder - Build emails with sugar

VERSION

       version 0.45

SYNOPSIS

           use Courriel::Builder;

           my $email = build_email(
               subject('An email for you'),
               from('joe@example.com'),
               to( 'jane@example.com', 'alice@example.com' ),
               header( 'X-Generator' => 'MyApp' ),
               plain_body($plain_text),
               html_body(
                   $html,
                   attach('path/to/image.jpg'),
                   attach('path/to/other-image.jpg'),
               ),
               attach('path/to/spreadsheet.xls'),
               attach( content => $file_content ),
           );

DESCRIPTION

       This module provides some sugar syntax for emails of all shapes sizes, from simple emails
       with a plain text body to emails with both plain and html bodies, html with attached
       images, etc.

API

       This module exports all of the following functions by default. It uses Sub::Exporter under
       the hood, which means you can easily import the functions with different names. See
       Sub::Exporter for details.

   build_email( ... )
       This function returns a new Courriel object. It takes the results of all the other
       functions you call as input.

       It expects you to pass in a body of some sort, whether text, html, or both, and will throw
       an error if you don't.

       It will add Date and Message-ID headers to your email if you don't provide them, ensuring
       that the email is RFC-compliant.

   subject($subject)
       This sets the subject of the email. It expects a single string. You can pass an empty
       string, but not "undef".

   from($from)
       This sets the From header of the email. It expects a single string or Email::Address
       object.

   to($from)
       This sets the To header of the email. It expects a list of string and/or Email::Address
       objects.

   cc($from)
       This sets the Cc header of the email. It expects a list of string and/or Email::Address
       objects.

   header( $name => $value )
       This sets a header's value. You can call it as many times as you want, and you can call it
       more than once with the same header name to set multiple values for that header.

   plain_body( ... )
       This defines a plain text body for the email. You can call it with a single argument, a
       scalar or reference to a scalar. This creates a text/plain part based on the content you
       provide in that argument. By default, the charset for the body is UTF-8 and the encoding
       is base64.

       You can also call this function with a hash of options. It accepts the following options:

       •   content

           The content of the body. This can be a string or scalar reference.

       •   charset

           The charset for the body. This defaults to UTF-8.

       •   encoding

           The encoding for the body. This defaults to base64. Other valid values are quoted-
           printable, 7bit, and 8bit.

           It is strongly recommended that you let Courriel handle the transfer encoding for you.

   html_body( ... )
       This accepts the same arguments as the "plain_body()" function.

       You can also pass in the results of one or more calls to the "attach()" function. If you
       pass in attachments, it creates a multipart/related email part, which lets you refer to
       images by the Content-ID using the "cid:" URL scheme.

   attach( ... )
       This function creates an attachment for the email. In the simplest form, you can pass it a
       single argument, which should be a path to a file on disk. This file will be attached to
       the email.

       You can also pass a hash of options. The valid keys are:

       •   file

           The file to attach to the email. You can also pass the content explicitly.

       •   content

           The content of the attachment. This can be a string or scalar reference.

       •   filename

           You can set the filename that will be used in the attachment's Content-Disposition
           header. If you pass a "file" parameter, that will be used when this isn't provided. If
           you pass as "content" parameter, then there will be no filename set for the attachment
           unless you pass a "filename" parameter as well.

       •   mime_type

           You can explicitly set the mime type for the attachment. If you don't, this function
           will use File::LibMagic to try to figure out the mime type for the attachment.

       •   content_id

           This will set the Content-ID header for the attachment. If you're creating a HTML body
           with "cid:" scheme URLs, you'll need to set this for each attachment that the HTML
           body refers to.

           The id will be wrapped in angle brackets ("<id-goes-here>") when set as a header.

COOKBOOK

       Some examples of how to build different types of emails.

   Simple Email With Plain Text Body
           my $email = build_email(
               subject('An email for you'),
               from('joe@example.com'),
               to( 'jane@example.com', 'alice@example.com' ),
               plain_body($plain_text),
           );

       This creates an email with a single text/plain part.

   Simple Email With HTML Body
           my $email = build_email(
               subject('An email for you'),
               from('joe@example.com'),
               to( 'jane@example.com', 'alice@example.com' ),
               html_body($html_text),
           );

       This creates an email with a single text/html part.

   Email With Both Plain and HTML Bodies
           my $email = build_email(
               subject('An email for you'),
               from('joe@example.com'),
               to( 'jane@example.com', 'alice@example.com' ),
               plain_body($plain_text),
               html_body($html_text),
           );

       This creates an email with this structure:

           multipart/alternative
             |
             |-- text/plain (disposition = inline)
             |-- text/html  (disposition = inline)

   Email With Both Plain and HTML Bodies and Inline Images
           my $email = build_email(
               subject('An email for you'),
               from('joe@example.com'),
               to( 'jane@example.com', 'alice@example.com' ),
               plain_body($plain_text),
               html_body(
                   $html_text,
                   attach(
                       file       => 'path/to/image1.jpg',
                       content_id => 'image1',
                   ),
                   attach(
                       file       => 'path/to/image2.jpg',
                       content_id => 'image2',
                   ),
               ),
           );

       This creates an email with this structure:

           multipart/alternative
             |
             |-- text/plain (disposition = inline)
             |-- multipart/related
                   |
                   |-- text/html  (disposition = inline)
                   |-- image/jpeg (disposition = attachment, Content-ID = image1)
                   |-- image/jpeg (disposition = attachment, Content-ID = image2)

   Email With Both Plain and HTML Bodies and Attachments
           my $email = build_email(
               subject('An email for you'),
               from('joe@example.com'),
               to( 'jane@example.com', 'alice@example.com' ),
               plain_body($plain_text),
               html_body(
                   $html_text,
               ),
               attach('path/to/spreadsheet.xls'),
               attach( content => \$png_image_content ),
           );

       This creates an email with this structure:

           multipart/mixed
             |
             |-- multipart/alternative
             |     |
             |     |-- text/plain (disposition = inline)
             |     |-- text/html  (disposition = inline)
             |
             |-- application/vnd.ms-excel (disposition = attachment)
             |-- image/png                (disposition = attachment)

SUPPORT

       Bugs may be submitted at <http://rt.cpan.org/Public/Dist/Display.html?Name=Courriel> or
       via email to bug-courriel@rt.cpan.org <mailto:bug-courriel@rt.cpan.org>.

       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".

SOURCE

       The source code repository for Courriel can be found at
       <https://github.com/houseabsolute/Courriel>.

AUTHOR

       Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2017 by Dave Rolsky.

       This is free software, licensed under:

         The Artistic License 2.0 (GPL Compatible)

       The full text of the license can be found in the LICENSE file included with this
       distribution.