view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        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' }

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

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

    "Username"
        Login name for SMTP authentication (SASL). Requires Authen::SASL.

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

    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 exception object, and returns "undef" in
    scalar context, or an empty list in list context.

  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.

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:

    "AutoFetch => $bool"
        When true and "KeyServer" is set, calls "gpg --locate-keys" for each
        recipient before encryption. Default: 0.

    "Digest => $algorithm"
        Hash algorithm for the signature embedded in the encrypted payload.
        Default: "SHA256".

    "GpgBin => $path"
        Full path to the "gpg" executable. Defaults to searching "gpg2" then
        "gpg" in "PATH".

    "KeyServer => $url"
        Keyserver URL for auto-fetching recipient public keys (e.g.
        'keys.openpgp.org'). Only consulted when "AutoFetch" is true.

  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:

    "Digest => $algorithm"
        Hash algorithm. Default: "SHA256".

        Valid values: "SHA256", "SHA384", "SHA512", "SHA1".

    "GpgBin => $path"
        Full path to the "gpg" executable.

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

  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 )
        $encrypted = $mail->smime_encrypt(
            RecipientCert => $smime_rec_cert,
        );

    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.

    Takes an hash or hash reference of options.

    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 )
        my $signed = $mail->smime_sign(
            Cert   => $smime_cert,
            Key    => $smime_key,
            CACert => $smime_ca, # optional
        );

    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.