NAME

Mail::Make - Strict, Fluent MIME Email Builder

SYNOPSIS

use Mail::Make;

# Fluent API
my $mail = Mail::Make->new
    ->from( 'hello@example.com' )
    ->to( 'jack@example.jp' )
    ->subject( "Q4 Report — Yamato, Inc." )
    ->plain( "Please find the report attached." )
    ->html( '<p>Please find the report <b>attached</b>.</p>' )
    ->attach_inline(
        path => '/var/www/images/Yamato,Inc-Logo.png',
        type => 'image/png',
        cid  => 'logo@yamato-inc',
    )
    ->attach(
        path     => '/tmp/Q4-Report.pdf',
        type     => 'application/pdf',
        filename => 'Q4 Report 2025.pdf',
    );

my $raw = $mail->as_string || die( $mail->error );
print $raw;

# Scalar-ref form — no string copy, useful for large messages
my $raw_ref = $mail->as_string_ref || die( $mail->error );
print $$raw_ref;

# Write directly to a filehandle — no in-memory buffering
open( my $fh, '>', '/tmp/message.eml' ) or die $!;
$mail->print( $fh ) || die( $mail->error );

# Send directly
$mail->smtpsend( Host => 'smtp.example.com' )
    || die( $mail->error );

# Direct access to the envelope headers object
my $h = $mail->headers;
$h->set( 'X-Priority' => '1' );

# Hash-based alternative constructor
my $mail2 = Mail::Make->build(
    from    => 'hello@example.com',
    to      => [ 'jack@example.jp' ],
    subject => 'Hello',
    plain   => "Hi there.\n",
    html    => '<p>Hi there.</p>',
) || die( Mail::Make->error );

VERSION

v0.21.0

DESCRIPTION

Mail::Make is a strict, validating MIME email builder with a fluent interface.

All RFC 2822 envelope fields (From, To, Cc, Bcc, Subject, Date, Message-ID, In-Reply-To, References, Reply-To, Sender) are stored in a Mail::Make::Headers instance accessible via "headers", eliminating any duplication between Mail::Make's own fields and the final entity's headers.

The MIME structure is assembled lazily when "as_entity", "as_string", or "print" is called. Structure selection is automatic:

plain only → text/plain
html only → text/html
plain + html → multipart/alternative
above + inline parts → wrapped in multipart/related
above + attachments → wrapped in multipart/mixed

Non-ASCII display names in address fields and non-ASCII subjects are RFC 2047 encoded automatically.

"as_string" returns a plain string, consistent with MIME::Entity::stringify.

"as_string_ref" returns a scalar reference to avoid a string copy, useful for large messages. "print" writes directly to a filehandle without buffering the message in memory at all, and is the recommended approach for very large messages.

When "use_temp_file" is set, or the assembled message size would exceed "max_body_in_memory_size", "as_string_ref" spools to a temporary file during serialisation and reads it back, keeping peak memory use to a single copy rather than two overlapping buffers.

CONSTRUCTOR

new( [%opts] )

Creates a new Mail::Make object. Optional %opts are passed through to "init" in Module::Generic.

build( %params )

An alternate hash-based constructor. Recognised keys: from, to, cc, bcc, date, reply_to, sender, subject, in_reply_to, message_id, references, plain, html, plain_opts, html_opts, headers.

Returns the populated Mail::Make object, or undef on error.

FLUENT METHODS

All setter methods return $self to allow chaining. Called without arguments, they act as getters and return the stored value (delegating to the internal Mail::Make::Headers object).

attach( %opts )

Adds a downloadable attachment. Required: path or data. Optional: type, filename, charset, encoding, description. All parameters are forwarded to "build" in Mail::Make::Entity.

attach_inline( %opts )

Adds an inline part (e.g. an embedded image referenced via cid: in HTML).

Required: (path or data) and (id or cid).

bcc( @addresses )

Accumulates one or more BCC addresses. May be called multiple times.

cc( @addresses )

Accumulates one or more CC addresses.

date( [$date_string_or_epoch] )

Gets or sets the Date header. Accepts a Unix epoch integer (converted to RFC 5322 format automatically) or a pre-formatted RFC 5322 string.

Delegates to "date" in Mail::Make::Headers. If not set explicitly, the current date and time are used when "as_entity" is first called.

from( [$address] )

Gets or sets the From header. Non-ASCII display names are RFC 2047 encoded automatically.

With two arguments: appends an arbitrary header to the envelope using push_header semantics (does not replace an existing field of the same name). Returns $self.

With one argument: returns the current value of the named header.

headers()

Returns the internal Mail::Make::Headers object. Use this for operations not covered by the fluent methods (e.g. setting X-* headers or reading back any field).

html( $content [, %opts] )

Adds a text/html body part. charset defaults to utf-8, encoding defaults to quoted-printable.

in_reply_to( [$mid] )

Gets or sets the In-Reply-To header.

message_id( [$mid | \%opts] )

Gets or sets the Message-ID. Auto-generated when "as_entity" is called if not explicitly set. Delegates to "message_id" in Mail::Make::Headers.

plain( $content [, %opts] )

Adds a text/plain body part. charset defaults to utf-8, encoding defaults to quoted-printable.

references( @mids )

Accumulates one or more Message-IDs in the References header.

reply_to( [$address] )

Gets or sets the Reply-To header.

sender( [$address] )

Gets or sets the Sender header.

subject( [$string] )

Gets or sets the Subject. Non-ASCII subjects are RFC 2047 encoded before being stored.

to( @addresses )

Accumulates one or more To addresses. Multiple calls are merged into a single To: field per RFC 5322 §3.6.3.

OUTPUT METHODS

as_entity

Assembles and returns the top-level Mail::Make::Entity. The MIME structure is selected automatically (see "DESCRIPTION"). Envelope headers are merged into the entity using init_header semantics: fields already set on the entity (Content-Type, MIME-Version, etc.) are never overwritten.

Returns undef and sets error() if assembly fails.

as_string

Assembles the message and returns it as a plain string, consistent with MIME::Entity::stringify. This is the form suitable for direct printing, string interpolation, and most downstream consumers.

For large messages, prefer "print" (no buffering) or "as_string_ref" (no copy on return).

Returns undef and sets error() on failure.

as_string_ref

Assembles the message and returns it as a scalar reference (or a Module::Generic::Scalar object, which stringifies as needed). No extra string copy is made during the fast path.

When "use_temp_file" is true, or the serialised entity size returned by "length" in Mail::Make::Entity exceeds "max_body_in_memory_size", the message is written to a Module::Generic::Scalar buffer via its in-memory filehandle. This keeps peak RAM use to a single copy of the assembled message.

Returns undef and sets error() on failure.

max_body_in_memory_size( [$bytes] )

Gets or sets the byte threshold above which "as_string_ref" spools to a temporary file rather than building the message in RAM. Set to 0 or undef to disable the threshold entirely. Default: $Mail::Make::MAX_BODY_IN_MEMORY_SIZE (1 MiB).

print( $fh )

Writes the fully assembled message to a filehandle without buffering it in memory. This is the recommended approach for very large messages: the MIME tree is serialised part by part directly to $fh, keeping memory use proportional to the largest single part rather than the total message size.

use_temp_file( [$bool] )

When true, "as_string_ref" always spools to a temporary file regardless of message size. Useful when you know the message will be large, or when you want to bound peak memory use unconditionally. Default: false.

smtpsend( %opts )

Assembles the message and submits it to an SMTP server via Net::SMTP, which is a core perl module.

Net::SMTP is loaded on demand.

Credential and recipient validation is performed before any network connection is attempted, so configuration errors are reported immediately without consuming network resources.

Recognised options:

Host

Hostname, IP address, or an already-connected Net::SMTP object. If an existing object is passed, it is used as-is and not quit on completion (the caller retains ownership of the connection).

If omitted, the colon-separated list in $ENV{SMTPHOSTS} is tried first, then mailhost and localhost in that order.

Port

SMTP port number. Common values:

25 — plain SMTP (default when SSL is false)
465 — SMTPS, direct SSL/TLS (use with SSL => 1)
587 — submission, usually STARTTLS (use with StartTLS => 1)

SSL

Boolean. When true, the connection is wrapped in SSL/TLS from the start (SMTPS, typically port 465).

Requires IO::Socket::SSL.

StartTLS

Boolean. When true, a plain connection is established first and then upgraded to TLS via the SMTP STARTTLS extension (typically port 587).

Requires IO::Socket::SSL. Ignored when Host is a pre-built Net::SMTP object.

SSL_opts

Hash reference of additional options passed to IO::Socket::SSL during the SSL/TLS handshake. For example:

SSL_opts => { SSL_verify_mode => 0 }           # disable peer cert check
SSL_opts => { SSL_ca_file => '/etc/ssl/ca.pem' }

Username

Must be combined with Password. Validated before any connection is made.

AuthMechanisms

Space-separated list of SASL mechanism names in preference order.

Defaults to "PLAIN LOGIN", which are safe and universally supported over an encrypted channel (STARTTLS or SSL).

The actual mechanism used is the intersection of this list and what the server advertises. If no intersection exists, deprecated challenge-response mechanisms (DIGEST-MD5, CRAM-MD5, GSSAPI) are excluded and the remainder of the server's list is tried.

Password

Password for SMTP authentication. May be:

A plain string.
A CODE reference called with no arguments at authentication time.

Useful for reading credentials from a keyring or secrets manager without storing them in memory until needed:
```
Password => sub { MyKeyring::get('smtp') }
```

MailFrom

The envelope sender address (MAIL FROM). Defaults to the bare addr-spec extracted from the From: header.

To, Cc, Bcc

Override the RCPT TO list. Each may be a string or an array reference of addresses. When omitted, the corresponding message headers are used.

Bcc: is always stripped from the outgoing message headers before transmission, per RFC 2822 §3.6.3.

Hello

The FQDN sent in the EHLO/HELO greeting.

Timeout

Connection and command timeout in seconds, passed directly to Net::SMTP.

Debug

Boolean. Enables Net::SMTP debug output.

Typical usage examples:

# Plain SMTP, no auth (LAN relay)
$mail->smtpsend( Host => 'mail.example.com' );

# SMTPS (direct TLS, port 465)
$mail->smtpsend(
    Host     => 'smtp.example.com',
    Port     => 465,
    SSL      => 1,
    Username => 'jack@example.com',
    Password => 'secret',
);

# Submission with STARTTLS (port 587) and password callback
$mail->smtpsend(
    Host     => 'smtp.example.com',
    Port     => 587,
    StartTLS => 1,
    Username => 'jack@example.com',
    Password => sub { MyKeyring::get('smtp_pass') },
);

Returns the list of accepted recipient addresses in list context, or a reference to that list in scalar context.

Returns undef and sets error() on failure.

GPG METHODS

These methods delegate to Mail::Make::GPG, which requires IPC::Run and a working gpg (or gpg2) installation. All three methods produce RFC 3156-compliant messages and return a new Mail::Make object suitable for passing directly to smtpsend().

gpg_encrypt( %opts )

Encrypts this message for one or more recipients and returns a new Mail::Make object whose entity is an RFC 3156 multipart/encrypted; protocol="application/pgp-encrypted" message.

Required options:

Recipients => \@addrs_or_key_ids: Array reference of recipient e-mail addresses or key fingerprints. Each recipient's public key must already be present in the local GnuPG keyring, unless AutoFetch is enabled.

Optional options:

GpgBin => $path: Full path to the gpg executable. Defaults to searching gpg2 then gpg in PATH.
Digest => $algorithm: Hash algorithm for the signature embedded in the encrypted payload. Default: SHA256.
KeyServer => $url: Keyserver URL for auto-fetching recipient public keys (e.g. 'keys.openpgp.org'). Only consulted when AutoFetch is true.
AutoFetch => $bool: When true and KeyServer is set, calls gpg --locate-keys for each recipient before encryption. Default: 0.

gpg_sign( %opts )

Signs this message and returns a new Mail::Make object whose entity is an RFC 3156 multipart/signed; protocol="application/pgp-signature" message with a detached, ASCII-armoured signature.

Required options:

KeyId => $fingerprint_or_id: Signing key fingerprint or short ID (e.g. '35ADBC3AF8355E845139D8965F3C0261CDB2E752').

Optional options:

Passphrase => $string_or_coderef

Passphrase to unlock the secret key. May be a plain string or a CODE reference called with no arguments at signing time. When omitted, GnuPG's agent handles passphrase prompting.

Digest => $algorithm

Hash algorithm. Default: SHA256.

Valid values: SHA256, SHA384, SHA512, SHA1.

GpgBin => $path

Full path to the gpg executable.

gpg_sign_encrypt( %opts )

Signs then encrypts this message. Returns a new Mail::Make object whose entity is an RFC 3156 multipart/encrypted message containing a signed and encrypted OpenPGP payload.

Accepts all options from both "gpg_sign" and "gpg_encrypt".

Note: KeyId and Recipients are both required.

Typical usage:

# Sign only
my $signed = $mail->gpg_sign(
    KeyId      => '35ADBC3AF8355E845139D8965F3C0261CDB2E752',
    Passphrase => 'my-passphrase',   # or: sub { MyKeyring::get('gpg') }
) || die $mail->error;
$signed->smtpsend( Host => 'smtp.example.com' );

# Encrypt only
my $encrypted = $mail->gpg_encrypt(
    Recipients => [ 'alice@example.com' ],
) || die $mail->error;

# Sign then encrypt
my $protected = $mail->gpg_sign_encrypt(
    KeyId      => '35ADBC3AF8355E845139D8965F3C0261CDB2E752',
    Passphrase => sub { MyKeyring::get_passphrase() },
    Recipients => [ 'alice@example.com', 'bob@example.com' ],
) || die $mail->error;

S/MIME METHODS

These methods delegate to Mail::Make::SMIME, which requires Crypt::SMIME (an XS module wrapping OpenSSL libcrypto). All certificates and keys must be supplied in PEM format, either as file paths or as PEM strings.

Memory usage

All three methods load the complete serialised message into memory before performing any cryptographic operation. This is a fundamental constraint imposed by two factors: the Crypt::SMIME API accepts only Perl strings (no filehandle or streaming interface), and the underlying protocols themselves require the entire content to be available before the result can be emitted, thus signing requires a complete hash before the signature can be appended, and PKCS#7 encryption requires the total payload length to be declared in the ASN.1 DER header before any ciphertext is written.

For typical email messages this is not a concern. If you anticipate very large attachments, consider Mail::Make::GPG instead, which delegates to the gpg command-line tool via IPC::Run and can handle arbitrary message sizes through temporary files. A future v0.2.0 of Mail::Make::SMIME may add a similar openssl smime backend.

See "MEMORY USAGE AND LIMITATIONS" in Mail::Make::SMIME for a full discussion.

smime_encrypt( %opts )

Encrypts this message for one or more recipients and returns a new Mail::Make object whose entity is an RFC 5751 application/pkcs7-mime; smime-type=enveloped-data message.

Required options:

RecipientCert => $pem_string_or_path: Recipient certificate in PEM format (for encryption). May also be an array reference of PEM strings or file paths for multi-recipient encryption.

Optional options:

CACert => $pem_string_or_path: CA certificate to include for chain verification.

smime_sign( %opts )

Signs this message with a detached S/MIME signature and returns a new Mail::Make object whose entity is an RFC 5751 multipart/signed message.

The signature is always detached, which allows non-S/MIME-aware clients to read the message body.

Required options:

Cert => $pem_string_or_path: Signer certificate in PEM format.
Key => $pem_string_or_path: Private key in PEM format.

Optional options:

KeyPassword => $string_or_coderef: Passphrase for an encrypted private key, or a CODE ref that returns one.
CACert => $pem_string_or_path: CA certificate to include in the signature for chain verification.

smime_sign_encrypt( %opts )

Signs this message then encrypts the signed result. Returns a new Mail::Make object whose entity is an RFC 5751 enveloped message containing a signed payload.

Accepts all options from both "smime_sign" and "smime_encrypt".

Note: Cert, Key, and RecipientCert are all required.

Typical usage:

# Sign only
my $signed = $mail->smime_sign(
    Cert   => '/path/to/my.cert.pem',
    Key    => '/path/to/my.key.pem',
    CACert => '/path/to/ca.crt',
) || die $mail->error;
$signed->smtpsend( Host => 'smtp.example.com' );

# Encrypt only
my $encrypted = $mail->smime_encrypt(
    RecipientCert => '/path/to/recipient.cert.pem',
) || die $mail->error;

# Sign then encrypt
my $protected = $mail->smime_sign_encrypt(
    Cert          => '/path/to/my.cert.pem',
    Key           => '/path/to/my.key.pem',
    RecipientCert => '/path/to/recipient.cert.pem',
) || die $mail->error;

PRIVATE METHODS

_default_domain

Returns a FQDN for auto-generated Message-ID values. Uses Sys::Hostname and appends .local when the hostname contains no dot.

Falls back to mail.make.local.

_encode_address( $addr_string )

Encodes the display-name portion of an RFC 2822 address using RFC 2047 when the display name contains non-ASCII characters. The addr-spec is never modified.

_encode_header( $string )

Encodes an arbitrary header string for the wire using RFC 2047 encoded-words.

Delegates to Mail::Make::Headers::Subject.

_format_date

Returns the current local date and time as an RFC 2822 string.

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Mail::Make, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mail::Make

CPAN shell

perl -MCPAN -e shell
install Mail::Make

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

VERSION

DESCRIPTION

CONSTRUCTOR

new( [%opts] )

build( %params )

FLUENT METHODS

attach( %opts )

attach_inline( %opts )

bcc( @addresses )

cc( @addresses )

date( [$date_string_or_epoch] )

from( [$address] )

header( $name [, $value] )

headers()

html( $content [, %opts] )

in_reply_to( [$mid] )

message_id( [$mid | \%opts] )

plain( $content [, %opts] )

references( @mids )

reply_to( [$address] )

sender( [$address] )

subject( [$string] )

to( @addresses )

OUTPUT METHODS

as_entity

as_string

as_string_ref

max_body_in_memory_size( [$bytes] )

print( $fh )

use_temp_file( [$bool] )

smtpsend( %opts )

GPG METHODS

gpg_encrypt( %opts )

gpg_sign( %opts )

gpg_sign_encrypt( %opts )

S/MIME METHODS

Memory usage

smime_encrypt( %opts )

smime_sign( %opts )

smime_sign_encrypt( %opts )

PRIVATE METHODS

_default_domain

_encode_address( $addr_string )

_encode_header( $string )

_format_date

AUTHOR

SEE ALSO

COPYRIGHT & LICENSE

Module Install Instructions