table of contents
Courriel::Builder(3pm) | User Contributed Perl Documentation | Courriel::Builder(3pm) |
NAME¶
Courriel::Builder - Build emails with sugarVERSION¶
version 0.47SYNOPSIS¶
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 an object with a "format()" method like "Email::Address::XS".to($from)¶
This sets the To header of the email. It expects a list of strings and/or objects with a "format()" method like "Email::Address::XS".cc($from)¶
This sets the Cc header of the email. It expects a list of strings and/or objects with a "format()" method like "Email::Address::XS".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 <https://github.com/houseabsolute/Courriel/issues>.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) 2018 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.
2018-05-22 | perl v5.26.2 |