Coding Domain Perl Modules: INet::Mailer

Perl Modules: INet::Mailer

Downloads

Perl Modules

Name

INet::Mailer - E-mails a message via SMTP

Synopsis

use INet::Mailer;

# Generating a message quickly
my $message1 = MakeMailMessage('Me', 'xx@yy.com', 'You', 'yy@@yy.com', 'Hello!', 'This is the message');
my $message2 = MakeMailMessage('Me', 'xx@yy.com', 'You', 'zz@@zz.com', 'Hi!', 'This is the message');

# Sending using the old functions
SendMail('/usr/bin/sendmail', MAILTYPE_SENDMAIL, 'xx@xx.com', 'yy@yy.com', $message1);
SendMail('mail.xx.com',       MAILTYPE_NETSMTP,  'xx@xx.com', 'yy@yy.com', $message1);

# Sending multiple e-mails using OO.
my $mail = new INet::Mailer('mail.xx.com', MAILTYPE_NETSMTP);
$mail->open();
$mail->send($message1, 'xx@xx.com', 'yy@yy.com');
$mail->send($message2, 'xx@xx.com', 'zz@zz.com');
$mail->close();

Description

This module can be used from any program written in Perl to send a e-mail. This modules uses a OO style, which is faster to use when a lot of e-mails have to be sent. The methods discussed belog will explain how this is done. See RFC 821 for more details about sending e-mails with the SMTP protocol.

Creating a New Object

$mailobj = new INet::Mailer( [COMMAND], CONSTANT );

The CONSTANT parameter is eiter MAILTYPE_SENDMAIL or MAILTYPE_NETSMTP. This parameter also defines what the COMMAND parameter's value should be.

For the MAILTYPE_SENDMAIL constant, the COMMAND parameter should be the location of the sendmail program. When using the MAILTYPE_NETSMTP constant, your COMMAND parameter defines the relayhost we should connect to, for example mail.yourdomain.com.

To use a default value, pass a undef value for this parameter.

Method Notes

The methods return nothing, or an empty list on success. When something failed, they return an array containing 2 elements. The first element contains a statuscode, which is also defined by some exported constant values. The 2nd argument contains a string with a status text, explaining the error code. Every status code below 1 implies an error occured.

The reason that this module doesn't throw any errors, is because that's difficult to handle in a CGI environment.

Methods

open()

Opens the connection, using the parameters you passed through at the object creation.

sendsimple(FROM_NAME, FROM_EMAIL, TO_NAME, TO_EMAIL, SUBJECT, BODY)

Sends the e-mail. Unlike the send method, this method handles all the difficult work for you. It formats the e-mail message in the right way. Internally, this simply calls the send method.

send(MESSAGE, FROM_EMAIL, TO_EMAIL, [TO_EMAIL2], [TO_EMAILN])

Sends the e-mail. You can call this method as many times as you need, without closing or re-opening the connection. This reduces the time required to sent the e-mails, if the Net::SMTP module is used. After a certain amount of e-mails, this method will automatically close and re-open a connection. Some SMTP servers don't allow too much e-mails being sent through the same connection.

The message argument contains the entire SMTP message, not just the body you always see in your e-mail program. This message can be generated with the MakeMailMessage subroutine, or you can make it yourself. If this is too difficult for you, simply use the sendsimple method.

The Net::SMTP approch requires that you specify the e-mail addresses before sending the e-mail itself. That's why you need to pass those addresses to this method aswell. Although the sendmail program does not require this approch, you'll have to do it anyway, since that makes this method portable for alternative sending methods.

abort()

Aborts the connection. This resets everything, but this doesn't cancel any e-mails that have already been sent.

close()

Closes the connection.

Old Functions (non methods)

These functions have been included to be compatible with older versions of this module, that did not implement OO.

SendMail( [COMMAND], TypeConstant, Message, [YourEmail, ToEmailArray] ): Sends a e-mail. This actually implements the methods described above.
MakeMailMessage( YourName, YourEmail, HisName, HisEmail, Subject, MessageBody ): This is a helper routine of users who don't have experience with sending e-mails withour their e-mail program. The message is generated, and can be passed though the SendMail routine, or the send method.

Exported Constants

The following constants are exported. The can either be used as parameter of the SendMail routine, or they will be returned by the SendMail routine and object methods.

MAILTYPE_SENDMAIL: This indicates that the UNIX program sendmail should be used to send the e-mail. Any return value of the program is not trapped, so you'll never find out whether the input of the e-mail was correctly.
MAILTYPE_NETSMTP: This indicates that the Net::SMTP module in Perl should be used to send the e-mail. This module is part of the libnet package, and can also be used to send e-mail from windows computers. Any step made in sending the e-mail will be trapped for errors, so a almost perfect error message will be available.
MAIL_SUCCESS: Successcode indicating that the e-mail has succesfully been sent.
MAILFAIL_PARAM: Errorcode indicating that the Type parameter is incorrect.
MAILFAIL_UNAVAILABLE: Errorcode indicating that either the Net::SMTP module or the sendmail program is not found on the webserver's system.
MAILFAIL_INIT: Errorcode indicating that the system failed to initialize contact with the mail server, or making a pipe with sendmail.
MAILFAIL_FROM: Returned only when used Net::SMTP. The from e-mail address is not accepted by the mail server.
MAILFAIL_RCPT: Returned only when used Net::SMTP. One of the receipients e-mail addresses is not accepted by the mail server.
MAILFAIL_INITSEND: Returned only when used Net::SMTP. Some information sent to the mailserver wasn't ok and not trapped. Now the mailserver prevents us from specifying the message to be sent.
MAILFAIL_SENDMSG: Returned only when used Net::SMTP. Strange, but the message is not accepted at all. Something may be wrong in the message.
MAILFAIL_SENDEND: Returned only when used Net::SMTP. Strange, but the end-code for the message is not accepted, or the message is considered incomplete.
MAILFAIL_CLOSE: Closing the connection with either the mailserver, or the sendmail program failed.

Message notes

A SMTP message should have this structure. Any other structure properly won't be permitted. This kind of structure is generated aswell by the MakeMailMessage subroutine.

to: $ToName<$ToEmail>
from: $FromName<$FromEmail>
subject: $Subject
X-Mailer: INet::Mailer Script in for Perl

$Body

Please note the empty line between the header, and the body contents of the e-mail. P.S. You don't need to convert any special escape characters in the mail contents. The Net::SMTP module does that for your (just for SMTP experts ;-).