view release on metacpan or  search on metacpan

lib/Mail/Make.pm  view on Meta::CPAN

=item C<AuthMechanisms>

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

Defaults to C<"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 (C<DIGEST-MD5>, C<CRAM-MD5>, C<GSSAPI>) are excluded and the remainder of the server's list...

=item C<Debug>

Boolean. Enables L<Net::SMTP> debug output.

=item C<Hello>

The FQDN sent in the EHLO/HELO greeting.

=item C<Host>

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

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

=item C<MailFrom>

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

=item C<Password>

Password for SMTP authentication. May be:

=over 4

=item * A plain string.

=item * A C<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') }

=back

=item C<Port>

SMTP port number. Common values:

=over 4

=item * C<25>  - plain SMTP (default when C<SSL> is false)

=item * C<465> - SMTPS, direct SSL/TLS (use with C<< SSL => 1 >>)

=item * C<587> - submission, usually STARTTLS (use with C<< StartTLS => 1 >>)

=back

=item C<SSL>

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

Requires L<IO::Socket::SSL>.

=item C<StartTLS>

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

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

=item C<SSL_opts>

Hash reference of additional options passed to L<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' }

=item C<Timeout>

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

=item C<To>, C<Cc>, C<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.

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

=item C<Username>

Login name for SMTP authentication (SASL). Requires L<Authen::SASL>.

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

=back

B<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.

If an error occurs, it sets an L<exception object|Mail::Make::Exception>, and returns C<undef> in scalar context, or an empty list in list context.

=head2 use_temp_file( [$bool] )

When true, L</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.

=head1 GPG METHODS

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

=head2 gpg_encrypt( %opts )

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