.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Courriel::Builder 3pm" .TH Courriel::Builder 3pm "2021-08-22" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Courriel::Builder \- Build emails with sugar .SH "VERSION" .IX Header "VERSION" version 0.49 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Courriel::Builder; \& \& my $email = build_email( \& subject(\*(AqAn email for you\*(Aq), \& from(\*(Aqjoe@example.com\*(Aq), \& to( \*(Aqjane@example.com\*(Aq, \*(Aqalice@example.com\*(Aq ), \& header( \*(AqX\-Generator\*(Aq => \*(AqMyApp\*(Aq ), \& plain_body($plain_text), \& html_body( \& $html, \& attach(\*(Aqpath/to/image.jpg\*(Aq), \& attach(\*(Aqpath/to/other\-image.jpg\*(Aq), \& ), \& attach(\*(Aqpath/to/spreadsheet.xls\*(Aq), \& attach( content => $file_content ), \& ); .Ve .SH "DESCRIPTION" .IX Header "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. .SH "API" .IX Header "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. .SS "build_email( ... )" .IX Subsection "build_email( ... )" This function returns a new Courriel object. It takes the results of all the other functions you call as input. .PP 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. .PP It will add Date and Message-ID headers to your email if you don't provide them, ensuring that the email is RFC-compliant. .SS "subject($subject)" .IX Subsection "subject($subject)" This sets the subject of the email. It expects a single string. You can pass an empty string, but not \f(CW\*(C`undef\*(C'\fR. .SS "from($from)" .IX Subsection "from($from)" This sets the From header of the email. It expects a single string or an object with a \f(CW\*(C`format()\*(C'\fR method like \f(CW\*(C`Email::Address::XS\*(C'\fR. .SS "to($from)" .IX Subsection "to($from)" This sets the To header of the email. It expects a list of strings and/or objects with a \f(CW\*(C`format()\*(C'\fR method like \f(CW\*(C`Email::Address::XS\*(C'\fR. .SS "cc($from)" .IX Subsection "cc($from)" This sets the Cc header of the email. It expects a list of strings and/or objects with a \f(CW\*(C`format()\*(C'\fR method like \f(CW\*(C`Email::Address::XS\*(C'\fR. .ie n .SS "header( $name => $value )" .el .SS "header( \f(CW$name\fP => \f(CW$value\fP )" .IX Subsection "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. .SS "plain_body( ... )" .IX Subsection "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 \s-1UTF\-8\s0 and the encoding is base64. .PP You can also call this function with a hash of options. It accepts the following options: .IP "\(bu" 4 content .Sp The content of the body. This can be a string or scalar reference. .IP "\(bu" 4 charset .Sp The charset for the body. This defaults to \s-1UTF\-8.\s0 .IP "\(bu" 4 encoding .Sp The encoding for the body. This defaults to base64. Other valid values are quoted-printable, 7bit, and 8bit. .Sp It is strongly recommended that you let Courriel handle the transfer encoding for you. .SS "html_body( ... )" .IX Subsection "html_body( ... )" This accepts the same arguments as the \f(CW\*(C`plain_body()\*(C'\fR function. .PP You can \fIalso\fR pass in the results of one or more calls to the \f(CW\*(C`attach()\*(C'\fR 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 \*(L"cid:\*(R" \s-1URL\s0 scheme. .SS "attach( ... )" .IX Subsection "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. .PP You can also pass a hash of options. The valid keys are: .IP "\(bu" 4 file .Sp The file to attach to the email. You can also pass the content explicitly. .IP "\(bu" 4 content .Sp The content of the attachment. This can be a string or scalar reference. .IP "\(bu" 4 filename .Sp You can set the filename that will be used in the attachment's Content-Disposition header. If you pass a \f(CW\*(C`file\*(C'\fR parameter, that will be used when this isn't provided. If you pass as \f(CW\*(C`content\*(C'\fR parameter, then there will be no filename set for the attachment unless you pass a \f(CW\*(C`filename\*(C'\fR parameter as well. .IP "\(bu" 4 mime_type .Sp 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. .IP "\(bu" 4 content_id .Sp This will set the Content-ID header for the attachment. If you're creating a \&\s-1HTML\s0 body with \*(L"cid:\*(R" scheme URLs, you'll need to set this for each attachment that the \s-1HTML\s0 body refers to. .Sp The id will be wrapped in angle brackets (\*(L"\*(R") when set as a header. .SH "COOKBOOK" .IX Header "COOKBOOK" Some examples of how to build different types of emails. .SS "Simple Email With Plain Text Body" .IX Subsection "Simple Email With Plain Text Body" .Vb 6 \& my $email = build_email( \& subject(\*(AqAn email for you\*(Aq), \& from(\*(Aqjoe@example.com\*(Aq), \& to( \*(Aqjane@example.com\*(Aq, \*(Aqalice@example.com\*(Aq ), \& plain_body($plain_text), \& ); .Ve .PP This creates an email with a single text/plain part. .SS "Simple Email With \s-1HTML\s0 Body" .IX Subsection "Simple Email With HTML Body" .Vb 6 \& my $email = build_email( \& subject(\*(AqAn email for you\*(Aq), \& from(\*(Aqjoe@example.com\*(Aq), \& to( \*(Aqjane@example.com\*(Aq, \*(Aqalice@example.com\*(Aq ), \& html_body($html_text), \& ); .Ve .PP This creates an email with a single text/html part. .SS "Email With Both Plain and \s-1HTML\s0 Bodies" .IX Subsection "Email With Both Plain and HTML Bodies" .Vb 7 \& my $email = build_email( \& subject(\*(AqAn email for you\*(Aq), \& from(\*(Aqjoe@example.com\*(Aq), \& to( \*(Aqjane@example.com\*(Aq, \*(Aqalice@example.com\*(Aq ), \& plain_body($plain_text), \& html_body($html_text), \& ); .Ve .PP This creates an email with this structure: .PP .Vb 4 \& multipart/alternative \& | \& |\-\- text/plain (disposition = inline) \& |\-\- text/html (disposition = inline) .Ve .SS "Email With Both Plain and \s-1HTML\s0 Bodies and Inline Images" .IX Subsection "Email With Both Plain and HTML Bodies and Inline Images" .Vb 10 \& my $email = build_email( \& subject(\*(AqAn email for you\*(Aq), \& from(\*(Aqjoe@example.com\*(Aq), \& to( \*(Aqjane@example.com\*(Aq, \*(Aqalice@example.com\*(Aq ), \& plain_body($plain_text), \& html_body( \& $html_text, \& attach( \& file => \*(Aqpath/to/image1.jpg\*(Aq, \& content_id => \*(Aqimage1\*(Aq, \& ), \& attach( \& file => \*(Aqpath/to/image2.jpg\*(Aq, \& content_id => \*(Aqimage2\*(Aq, \& ), \& ), \& ); .Ve .PP This creates an email with this structure: .PP .Vb 8 \& 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) .Ve .SS "Email With Both Plain and \s-1HTML\s0 Bodies and Attachments" .IX Subsection "Email With Both Plain and HTML Bodies and Attachments" .Vb 11 \& my $email = build_email( \& subject(\*(AqAn email for you\*(Aq), \& from(\*(Aqjoe@example.com\*(Aq), \& to( \*(Aqjane@example.com\*(Aq, \*(Aqalice@example.com\*(Aq ), \& plain_body($plain_text), \& html_body( \& $html_text, \& ), \& attach(\*(Aqpath/to/spreadsheet.xls\*(Aq), \& attach( content => \e$png_image_content ), \& ); .Ve .PP This creates an email with this structure: .PP .Vb 9 \& multipart/mixed \& | \& |\-\- multipart/alternative \& | | \& | |\-\- text/plain (disposition = inline) \& | |\-\- text/html (disposition = inline) \& | \& |\-\- application/vnd.ms\-excel (disposition = attachment) \& |\-\- image/png (disposition = attachment) .Ve .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted at . .PP I am also usually active on \s-1IRC\s0 as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR. .SH "SOURCE" .IX Header "SOURCE" The source code repository for Courriel can be found at . .SH "AUTHOR" .IX Header "AUTHOR" Dave Rolsky .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2021 by Dave Rolsky. .PP This is free software, licensed under: .PP .Vb 1 \& The Artistic License 2.0 (GPL Compatible) .Ve .PP The full text of the license can be found in the \&\fI\s-1LICENSE\s0\fR file included with this distribution.