--- name: "Courriel::Builder" section: "3pm" platform: "linux" package: "libcourriel-perl" version: "0.49-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Courriel::Builder" --- # Courriel::Builder(3pm) Build emails with sugar ## NAME Courriel::Builder - Build emails with sugar ## VERSION version 0.49 ## 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 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 ("\") 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 \. 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 \. ## AUTHOR Dave Rolsky \ ## COPYRIGHT AND LICENSE This software is Copyright (c) 2021 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.