NAME

Web::VWF::Mail - send mail through sendmail(1), DKIM signed when configured

SYNOPSIS

my $mail = Web::VWF::Mail->new(
	from => 'no-reply@example.com',
	domain => 'example.com',
	selector => '202611',
	keyfile => '/home/site/dkim/202611.private',
);

$mail->print("To: someone\@example.com\n",
	"From: \"Example\" <no-reply\@example.com>\n",
	"Subject: hello\n\n",
	"Body\n");

$mail->close or warn 'the message was not delivered';

DESCRIPTION

Buffers a message and, at "close", signs it with DKIM if the site has a key and then pipes it to sendmail(1) with -t.

Signing is skipped, and the message is sent unsigned, when domain, selector or keyfile is unset, when the key cannot be read, and when Mail::DKIM is not installed or cannot produce a signature. Each of those cases warns, because an unsigned message from a site that expects to sign is worth looking at - but it is still sent.

METHODS

new

Takes a hash or a hash reference of:

from     - envelope sender, also given to sendmail -f (required)
domain   - the domain to sign for; signing is skipped if unset
selector - the DKIM selector, e.g. 202611; signing is skipped if unset
keyfile  - path to the PEM private key; signing is skipped if unset
sendmail - the program to run, defaulting to /usr/sbin/sendmail

The envelope sender matters as much as the header: sendmail fills in the web user and this host when it is given nothing, and a receiving site is entitled to reject that.

new croaks, with from is required, when from is missing, and with from is not a valid envelope sender when it holds a control character, a space or a leading -. The address is passed to sendmail(1) as an argument, and a value such as -X/etc/passwd or one with a line break in it would otherwise be read as an option or as an extra header.

API SPECIFICATION

INPUT

{
	from => { type => 'string', min => 1 },
	domain => { type => 'string', optional => 1 },
	selector => { type => 'string', optional => 1 },
	keyfile => { type => 'string', optional => 1 },
	sendmail => { type => 'string', optional => 1 },
}

OUTPUT

{ type => 'object', isa => 'Web::VWF::Mail' }

print

Appends text to the message. The arguments are joined exactly as print would join them, so a caller can keep writing one print statement per header. It always returns true.

API SPECIFICATION

INPUT

{ text => { type => 'string', optional => 1 } }	# any number of strings

OUTPUT

{ type => 'integer', value => 1 }

close

Signs the message, pipes it to sendmail(1), and returns true if sendmail exited cleanly. Calling it a second time returns the first result without sending the message again, so it is safe in an END block.

It returns false, after a carp naming the program and the reason, when sendmail(1) cannot be run, and false when it can be run but exits with a failure status or the message cannot be written to it. Problems with signing are never failures: they warn, and the message goes out unsigned.

API SPECIFICATION

INPUT

{}

OUTPUT

{ type => 'integer', min => 0, max => 1 }	# 1 if sendmail exited cleanly

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

Usage is subject to the GPL2 licence terms. If you use it, please let me know.