/ 
Mail-Sender-0.6.7
River stage one • 5 direct dependents • 5 total dependents
/ Mail::Sender

NAME

Mail::Sender - module for sending mails with attachments through an SMTP server

Version 0.6.7

SYNOPSIS

use Mail::Sender;
$sender = new Mail::Sender
 {smtp => 'mail.yourdomain.com', from => 'your@address.com'};
$sender->MailFile({to => 'some@address.com',
 subject => 'Here is the file',
 msg => "I'm sending you the list you wanted.",
 file => 'filename.txt'});

DESCRIPTION

Mail::Sender provides an object oriented interface to sending mails. It doesn't need any outer program. It connects to a mail server directly from Perl, using Socket.

Sends mails directly from Perl through a socket connection.

CONSTRUCTORS

new Mail::Sender ([from [,replyto [,to [,smtp [,subject [,headers [,boundary]]]]]]])
new Mail::Sender {[from => 'somebody@somewhere.com'] , [to => 'else@nowhere.com'] [...]}
.

Prepares a sender. This doesn't start any connection to the server. You have to use $Sender-Open> or $Sender-OpenMultipart> to start talking to the server.

The parameters are used in subsequent calls to $Sender-Open> and $Sender-OpenMultipart>. Each such call changes the saved variables. You can set smtp,from and other options here and then use the info in all messages.

from      = the senders e-mail address

replyto   = the reply-to address

to        = the recipient's address(es)

cc        = address(es) to send a copy (carbon copy)

bcc       = address(es) to send a copy (blind carbon copy)
            these adresses will not be visible in the mail!

smtp      = the IP or domain addres of you SMTP (mail) server

subject   = the subject of the message

headers   = the additional headers

boundary  = the message boundary


return codes:
 ref to a Mail::Sender object =  success
 -1 = $smtphost unknown
 -2 = socket() failed
 -3 = connect() failed
 -4 = service not available
 -5 = unspecified communication error
 -6 = local user $to unknown on host $smtp
 -7 = transmission of message failed
 -8 = argument $to empty
 -9 = no message specified in call to MailMsg or MailFile
 -10 = no file name specified in call to SendFile or MailFile
 -11 = file not found
 -12 = not available in singlepart mode
  Mail::Sender::Error contains a textual description of last error.

METHODS

Open([from [, replyto [, to [, smtp [, subject [, headers]]]]]])
Open({[from => "somebody@somewhere.com"] , [to => "else@nowhere.com"] [...]})
.

Opens a new message. If some parameters are unspecified or empty, it uses the parameters passed to the "$Sender=new Mail::Sender(...)";

see new Mail::Sender for info about the parameters.

OpenMultipart([from [, replyto [, to [, smtp [, subject [, headers [, boundary]]]]]]])
OpenMultipart({[from => "somebody@somewhere.com"] , [to => "else@nowhere.com"] [...]})
.

Opens a multipart message. If some parameters are unspecified or empty, it uses the parameters passed to the $Sender=new Mail::Sender(...).

see new Mail::Sender for info about the parameters.

MailMsg([from [, replyto [, to [, smtp [, subject [, headers]]]]]], message)
MailMsg({[from => "somebody@somewhere.com"] [, to => "else@nowhere.com"] [...], msg => "Message"})
.

Sends a message. If a mail in $sender is opened it gets closed and a new mail is created and sent. $sender is then closed. If some parameters are unspecified or empty, it uses the parameters passed to the "$Sender=new Mail::Sender(...)";

see new Mail::Sender for info about the parameters.

MailFile([from [, replyto [, to [, smtp [, subject [, headers]]]]]], message, file(s))
MailFile({[from => "somebody@somewhere.com"] [, to => "else@nowhere.com"] [...], msg => "Message", file => "File"})
.

Sends one or more files by mail. If a mail in $sender is opened it gets closed and a new mail is created and sent. $sender is then closed. If some parameters are unspecified or empty, it uses the parameters passed to the "$Sender=new Mail::Sender(...)";

The file parameter may be a "filename", a "list, of, file, names" or a \@list of file names.

see new Mail::Sender for info about the parameters.

Send(@strings)

Prints the strings to the socket. Doesn't add any end-of-line characters. You should use \r\n as the end-of-line.

SendLine(@strings)

Prints the strings to the socket. Add the end-of-line character at the end.

SendEnc(@strings)

Prints the strings to the socket. Doesn't add any end-of-line characters. You should use \r\n as the end-of-line. Encodes the text using the selected encoding (Base64/Quoted-printable)

SendLineEnc(@strings)

Prints the strings to the socket. Add the end-of-line character at the end. Encodes the text using the selected encoding (Base64/Quoted-printable)

Do NOT mix up Send[Line][Ex] and Send[Line]Enc! SendEnc does some buffering necessary for correct Base64 encoding, and Send is not aware of that!

Ussage of Send[Line][Ex] in non 7BIT parts not recommended. Using Send(encode_base64($string)) may, but may NOT work! In particular if you use several such to create one part, the data is very likely to get crippled.

SendEx(@strings)

Prints the strings to the socket. Doesn't add any end-of-line characters. Changes all end-of-lines to \r\n.

SendLineEx(@strings)

Prints the strings to the socket. Doesn't add any end-of-line characters. Changes all end-of-lines to \r\n.

Part( description, ctype, encoding, disposition, autocode);
Part( { [description => "desc"] , [ctype], [encoding], [disposition]});
Prints a part header for the multipart message.
The undef or empty variables are ignored.
description

The title for this part.

ctype

the content type (MIME type) of this part. May contain some other parameters, such as charset or name.

Defaults to "application/octet-stream".

encoding

the encoding used for this part of message. Eg. Base64, Uuencode, 7BIT ...

Defaults to "7BIT".

disposition

This parts disposition. Eg: 'attachment; filename="send.pl"'.

Defaults to "attachment".

Body([charset [, encoding [, content-type]]]);

Sends the head of the multipart message body. You can specify the charset and the encoding. Default is "US-ASCII","7BIT",'text/plain'.

If you pass undef or zero as the parameter, this function uses the default value:

Body(0,0,'text/html');
SendFile( description, ctype, encoding, disposition, file);
SendFile( { [description => "desc"] , [ctype => "ctype"], [encoding => "encoding"], [disposition => "disposition"], file => "file"});
Sends a file as a separate part of the mail mesage. Only in multipart mode.
description

The title for this part.

ctype

the content type (MIME type) of this part. May contain some other parameters, such as charset or name.

Defaults to "application/octet-stream".

encoding

the encoding used for this part of message. Eg. Base64, Uuencode, 7BIT ...

Defaults to "Base64".

disposition

This parts disposition. Eg: 'attachment; filename="send.pl"'.

Defaults to "attachment".

file

The name of the file to send or a 'list, of, names' or a ['reference','to','a','list','of','filenames']. Each file will be sent as a separate part.

Close;

Close and send the mail. This method should be called automaticaly when destructing the object, but you should call it yourself just to be sure it gets called. And you should do it as soon as posible to close the connection and free the socket.

The mail is being sent to server, but is not processed by the server till the sender object is closed!

Cancel;

Cancel an opened message.

SendFile and other methods may set $sender->{'error'}. In that case "undef $sender" calls $sender->Cancel not $sender->Close!!!

@Mail::Sender::Errors

Contains the description of errors returned by functions in Mail::Sender.

Ussage: @Mail::Sender::Errors[$sender->{error}]

EXAMPLES

use Mail::Sender;

#$sender = new Mail::Sender { from => 'somebody@somewhere.com',
   smtp => 'ms.chipnet.cz', boundary => 'This-is-a-mail-boundary-435427'};
# # if you do not care about errors.
# # otherwise use
#
ref ($sender = new Mail::Sender { from => 'somebody@somewhere.com',
      smtp => 'ms.chipnet.cz', boundary => 'This-is-a-mail-boundary-435427'})
or die "Error($sender) : $Mail::Sender::Error\n";

$sender->Open({to => 'friend@other.com', subject => 'Hello dear friend'});
$sender->SendLine("How are you?");
$sender->SendLine;
$sender->Send(<<'*END*');
I've found these jokes.

 Doctor, I feel like a pack of cards.
 Sit down and I'll deal with you later.

 Doctor, I keep thinking I'm a dustbin.
 Don't talk rubbish.

Hope you like'em. Jenda
*END*

$sender->Close;

$sender->Open({to => 'mama@home.org, papa@work.com',
               cc => 'somebody@somewhere.com',
               subject => 'Sorry, I'll come later.'});
$sender->SendLine("I'm sorry, but due to a big load of work,
   I'll come at 10pm at best.");
$sender->SendLine("\nHi, Jenda");

$sender->Close;

$sender->OpenMultipart({to => 'Perl-Win32-Users@activeware.foo',
                        subject => 'Mail::Sender.pm - new module'});
$sender->Body;
$sender->Send(<<'*END*');
Here is a new module Mail::Sender.
It provides an object based interface to sending SMTP mails.
It uses a direct socket connection, so it doesn't need any
additionl program.

Enjoy, Jenda
*END*
$sender->SendFile(
 {description => 'Perl module Mail::Sender.pm',
  ctype => 'application/x-zip-encoded',
  encoding => 'Base64',
  disposition => 'attachment; filename="Sender.zip"; type="ZIP archive"',
  file => 'sender.zip'
 });
$sender->Close;

_END_

If everything you need is to send a simple message you may use:

use Mail::Sender;

ref ($sender = new Mail::Sender({from => 'somebody@somewhere.com',smtp
=> 'ms.chipnet.cz'})) or die "$Mail::Sender::Error\n";

(ref ($sender->MailMsg({to =>'Jenda@Krynicky.cz', subject => 'this is a test',
                        msg => "Hi Johnie.\nHow are you?"}))
 and print "Mail sent OK."
)
or die "$Mail::Sender::Error\n";

If you want to attach some files:

use Mail::Sender;

ref ($sender = new Mail::Sender({from => 'somebody@somewhere.com',smtp
=> 'mail.yourdomain.com'})) or die "$Mail::Sender::Error\n";

(ref ($sender->MailFile(
 {to =>'you@address.com', subject => 'this is a test',
  msg => "Hi Johnie.\nI'm sending you the pictures you wanted.",
  file => 'image1.jpg,image2.jpg'
 }))
 and print "Mail sent OK."
)
or die "$Mail::Sender::Error\n";

If you want to send a HTML mail:

use Mail::Sender;
open IN, $htmlfile or die "Cannot open $htmlfile : $!\n";
$sender = new Mail::Sender {smtp => 'mail.yourdomain.com'};
$sender->Open({ from => 'your@address.com', to => 'other@address.com', subject => 'HTML test',
       headers => "MIME-Version: 1.0\r\nContent-type: text/html\r\nContent-Transfer-Encoding: 7bit"
}) or die $Mail::Sender::Error,"\n";

while (<IN>) { $sender->Send($_) };
close IN;
$sender->Close();

DO NOT mix Open(Multipart)|Send(Line)(Ex)|Close with MailMsg or MailFile. Both Send(Msg/File) close any Open-ed mail. Do not try this:

$sender = new Mail::Sender ...;
$sender->OpenMultipart...;
$sender->Body;
$sender->Send("...");
$sender->MailFile({file => 'something.ext');
$sender->Close;

This WON'T work!!!

DISCLAIMER

This module is based on SendMail.pm Version : 1.21 that appeared in Perl-Win32-Users@activeware.com mailing list. I don't remember the name of the poster and it's not mentioned in the script. Thank you mr. undef.

AUTHOR

Jan Krynicky <Jenda@Krynicky.cz>

COPYRIGHT

Copyright (c) 1997 Jan Krynicky <Jenda@Krynicky.cz>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.