view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    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](https://metacpan.org/pod/IO%3A%3ASocket%3A%3ASSL). Ignored when `Host` is a pre-built [Net::SMTP](https://metacpan.org/pod/Net%3A%3ASMTP) object.

- `SSL_opts`

    Hash reference of additional options passed to [IO::Socket::SSL](https://metacpan.org/pod/IO%3A%3ASocket%3A%3ASSL) 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](https://metacpan.org/pod/Net%3A%3ASMTP).

- `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](https://metacpan.org/pod/Authen%3A%3ASASL).

    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](https://metacpan.org/pod/Mail%3A%3AMake%3A%3AException), and returns `undef` in scalar context, or an empty list in list context.

## use\_temp\_file( \[$bool\] )

When true, ["as\_string\_ref"](#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](https://metacpan.org/pod/Mail%3A%3AMake%3A%3AGPG), which requires [IPC::Run](https://metacpan.org/pod/IPC%3A%3ARun) and a working `gpg` (or `gpg2`) installation. All three methods produce RFC 3156-compliant...

## gpg\_encrypt( %opts )

Encrypts this message for one or more recipients and returns a new [Mail::Make](https://metacpan.org/pod/Mail%3A%3AMake) 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](https://metacpan.org/pod/Mail%3A%3AMake) 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](https://metacpan.org/pod/Mail%3A%3AMake) object whose entity is an RFC 3156 `multipart/encrypted` message containing a signed and encrypted OpenPGP payload.

Accepts all options from both ["gpg\_sign"](#gpg_sign) and ["gpg\_encrypt"](#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](https://metacpan.org/pod/Mail%3A%3AMake%3A%3ASMIME), which requires [Crypt::SMIME](https://metacpan.org/pod/Crypt%3A%3ASMIME) (an XS module wrapping OpenSSL `libcrypto`). All certificates and keys must be...

## 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](https://metacpan.org/pod/Crypt%3A%3ASMIME) API accepts only ...

For typical email messages this is not a concern. If you anticipate very large attachments, consider [Mail::Make::GPG](https://metacpan.org/pod/Mail%3A%3AMake%3A%3AGPG) instead, which delegates to the `gpg` command-line tool via [IPC::Run](https://me...

See ["MEMORY USAGE AND LIMITATIONS" in Mail::Make::SMIME](https://metacpan.org/pod/Mail%3A%3AMake%3A%3ASMIME#MEMORY-USAGE-AND-LIMITATIONS) 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.

## smime\_sign\_encrypt( %opts )

    my $result = $mail->smime_sign_encrypt(