Dave Rolsky > Courriel > Courriel::Builder

Download:
Courriel-0.33.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  1
Stalled  1
View/Report Bugs
Module Version: 0.33   Source  

NAME ^

Courriel::Builder - Build emails with sugar

VERSION ^

version 0.33

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($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:

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:

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)

AUTHOR ^

Dave Rolsky <autarch@urth.org>

CONTRIBUTOR ^

Zbigniew Łukasiak <zzbbyy@gmail.com>

COPYRIGHT AND LICENSE ^

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

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)
syntax highlighting: