NAME

Net::QMTP - Quick Mail Transfer Protocol (QMTP) client

SYNOPSIS

 use Net::QMTP;

 $qmtp = Net::QMTP->new('mail.example.org');

 $qmtp->sender('sender@example.org');
 $qmtp->recipient('foo@example.org');
 $qmtp->recipient('bar@example.org');

 $qmtp->message($bodytext);

 $qmtp->encoding('unix');
 $qmtp->message_from_file($filename);

 $qmtp->host('server.example.org');

 $qmtp->send();

DESCRIPTION

This module implements an object orientated interface to a Quick Mail Transfer Protocol (QMTP) client which enables a perl program to send email by QMTP.

CONSTRUCTOR

Net::QMTP->new(HOST)

The new() constructor creates an new Net::QMTP object and returns a reference to it if successful, undef otherwise. HOST is an FQDN or IP address of the QMTP server to connect to and it is mandatory.

METHODS

sender(ADDRESS) sender()

Return the envelope sender for this object or set it to the supplied ADDRESS. Returns undef if the sender is not yet defined.

recipient(ADDRESS) recipient()

If supplied, add ADDRESS to the list of envelope recipients. If not, return a reference to the current list of recipients. Returns a reference to an empty list if recipients have not yet been defined.

host(SERVER) host()

If supplied, set SERVER as the QMTP server this object will connect to. If not, return the current server.

message(TEXT) message()

If supplied, append TEXT to the message body. If not, return the current message body. It is the programmer's responsibility to create a valid message including appropriate RFC2822/RFC822 header lines.

This method cannot be used on a object which has had a message body created by the message_from_file method.

message_from_file(FILE)

Use the contents of FILE as the message body. It is the programmer's responsibility to create a valid message in FILE including appropriate RFC2822/RFC822 header lines.

This method cannot be used on a object which has had a message body created by the message method.

encoding(TYPE) encoding()

Set the line-ending encoding for this object to one of:

unix - Unix-like line ending; lines are delimited by a line-feed character.

dos - DOS/Windows line ending; lines are delimited by a carraige-return line-feed character pair.

The new method will make a guess at which encoding to use based on the value of $/. Call encoding method without an argument to get the current line-encoding. It will return a line-feed for unix, a carraige-return for dos or undef if the encoding couldn't be set.

Be sure the messages you create with message and message_from_file have approproiate line-endings.

send()

Send the message. It returns a reference to a hash. The hash is keyed by recipient address. The value for each key is the response from the QMTP server, prepended with one of:

success: - the message was accepted for delivery

deferral: - temporary failure. The client should try again later

failure: - permanent failure. The message was not accepted and should not be tried again

NOTES

The QMTP protocol is described in http://cr.yp.to/proto/qmtp.txt

QMTP is a replacement for SMTP and, as such, requires a QMTP server in addition to this client. The qmail MTA includes a QMTP server; qmail-qmtpd. Setting up the server is outside the scope of the module's documentation.

CAVEATS

Be aware of your line endings! \n means different things on different platforms.

If, on a Unix system, you say:

 $qmtp->encoding("dos");
 

with the intention of later supplying a DOS formatted file, don't make the mistake of substituting message_from_file with something like:

 $qmtp->message($lineone . "\n" . $linetwo);

On Unix systems \n is (only) a line-feed. You should either explicitly change the encoding back to unix or supply your text with the proper encoding:

 $qmtp->message($lineone . "\r\n" . $linetwo);

AUTHOR

James Raftery <james@now.ie>.

SEE ALSO

qmail-qmtpd(8), maildirqmtp(1).