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

    Version 0.7.03

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'
       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 addresses will not be visible in the mail!

       smtp      = the IP or domain address of your SMTP (mail) server
                   This is the name of your LOCAL mail server, do not try to guess
                   and contact directly the adressee's mailserver!

       subject   = the subject of the message

       headers   = the additional headers

       boundary  = the message boundary

       multipart = the MIME subtype for the whole message (Mixed/Related/Alternative)
        you may need to change this setting if you want to send a HTML body with some
        inline images, or if you want to post the message in plain text as well as
        HTML (alternative). See the examples at the end of the docs.
        You may also use the nickname "subtype".

       type      = the content type of a multipart message, may be usefull for
                   multipart/related

       ctype     = the content type of a single part message

        Please do not confuse these two. The 'type' parameter is used to specify
        the overall content type of a multipart message (for example a HTML document
        with inlined images) while ctype is an ordinary content type for a single
        part message. For example a HTML mail message.

       encoding  = encoding of a single part message or the body of a multipart
        message. If the text of the message contains some extended characters or
        very long lines you should use 'encoding => "Quoted-printable"' in the
        call to Open(), OpenMultipart(), MailMsg() or MailFile().
        Keep in mind that if you use some encoding you should either use SendEnc()
        or encode the data yourself !

       charset   = the charset of the message

       client     = the name of the client computer. During the connection you send
        the mailserver your name. Usualy a "localhost" is sufficient, but sometimes
        you need to specify some real name. Usualy something like
        `hostname`.'.mycompany.com'. But I leave this for you.
        Mail::Sender doesn't try to guess the name, it sends "localhost" if you do
        not specify otherwise.

       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
       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
       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
       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
       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.

      Just keep in mind that parameters like ctype, charset and
      encoding will be used for the attached file, not the body of
      the message. If you want to specify those parameters for the
      body you have to use b_ctype, b_charset and b_encoding. Sorry.

    Send
       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
       SendLine(@strings)

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

    SendEnc
       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
       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!

      Usage 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
       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
       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
       Part( I<description>, I<ctype>, I<encoding>, I<disposition> [, I<content_id>]);
       Part( [description => "desc"], [ctype], [encoding], [disposition], [content_id]});

       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". If you specify "none" or "", the
        Content-disposition: line will not be included in the
        headers.

    content_id
        The content id of the part, used in multipart/related. If
        not specified, the header is not included.

    Body
       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
       SendFile( I<description>, I<ctype>, I<encoding>, I<disposition>, I<file>);
       SendFile( { [description => "desc"] , [ctype => "ctype"], [encoding => "encoding"],
                   [disposition => "disposition"], file => "file"});

       Sends a file as a separate part of the mail message. 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"'. If you use 'attachment; filename=*' the
        * will be replaced by the respective names of the sent
        files.

        Defaults to "attachment; filename=*". If you do not want to
        include this header use "" as the value.

    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.

    content_id
        The content id of the message part. Used in
        multipart/related.

         Special values:
          "*" => the name of the file
          "#" => autoincremented number (starting from 0)

    Close
       $sender->Close;

      Close and send the mail. This method should be called
      automatically 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 possible 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
       $sender->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.

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

CONFIG
    If you create a file named Sender.config in the same directory
    where Sender.pm resides, this file will be "require"d as soon as
    you "use Mail::Sender" in your script. Of course the
    Sender.config MUST "return a true value", that is it has to be
    succesfully compiled and the last statement must return a true
    value. You may use this to forbide the use of Mail::Sender to
    some users.

    You may define the default settings for new Mail::Sender objects
    and do a few more things.

    The default options are stored in hash %Mail::Sender::default.
    You may use all the examples you'd use in `new', `Open',
    `OpenMultipart', `MailMsg' or `MailFile'.

     Eg.
      %default = (
        smtp => 'mail.mccann.cz',
        from => Win32::LoginName.'@mccann.cz',
        client => Win32::NodeName.'mccann.cz'
      );
      # of course you will use your own mail server here !

    The other options you may set here (or later of course) are
    $Mail::Sender::SITE_HEADERS and $Mail::Sender::NO_X_MAILER.

    The $Mail::Sender::SITE_HEADERS may contain headers that will be
    added to each mail message sent by this script, the
    $Mail::Sender::NO_X_MAILER disables the header item specifying
    that the message was sent by Mail::Sender.

    !!! $Mail::Sender::SITE_HEADERS may NEVER end with \r\n !!!

    If you want to set the $Mail::Sender::SITE_HEADERS for every
    script sent from your server without your users being able to
    change it you may use this hack:

     $loginname = something_that_identifies_the_user();
     eval qq{*Mail::Sender::SITE_HEADERS = 'X-Sender: $loginname via $0'};

    You may even "install" your custom function that will be
    evaluated for each message just before contacting the server.
    You may change all the options from within as well as stop
    sending the message.

    All you have to do is to create a function named SiteHook in
    Mail::Sender package. This function will get the Mail::Sender
    object as its first argument. If it returns a TRUE value the
    message is sent, if it returns FALSE the sending is canceled and
    the user gets "Site specific error" error message.

    If you want to give some better error message you may do it like
    this :

     sub SiteHook {
      my $self = shift;
      if (whatever($self)) {
        $self->{'error'} = SITEERROR;
        $Mail::Sender::Error = "I don't like this mail";
        return 0
      } else {
        return 1;
      }
     }

    This example will ensure the from address is the users real
    address :

     sub SiteHook {
      my $self = shift;
      $self->{fromaddr} = getlogin.'@yoursite.com';
      $self->{from} = getlogin.'@yoursite.com';
      1;
     }

    Please note that at this stage the from address is in two
    different object properties.

    $self->{from} is the address as it will appear in the mail, that
    is it may include the full name of the user or any other comment
    ( "Jan Krynicky <jenda@krynicky.cz>" for example), while the
    $self->{fromaddr} is realy just the email address per se and it
    will be used in conversation with the SMTP server. It must be
    without comments ("jenda@krynicky.cz" for example)!

    Without write access to .../lib/Mail/Sender.pm or
    .../lib/Mail/Sender.config your users will then be unable to get
    rid of this header. Well ... everything is doable, if he's
    cheeky enough ... :-(

    So if you take care of some site with virtual servers for
    several clients and implement some policy via SiteHook() or
    $Mail::Sender::SITE_HEADERS search the clients' scripts for
    "SiteHook" and "SITE_HEADERS" from time to time. To see who's
    cheating.

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
     additional 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";
     __END__

    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";
     __END__

    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();
     __END__

    If you want to send a HTML with some inline images :

     use strict;
     use Mail::Sender;
     my $recipients = 'somebody@somewhere.com';
     my $sender = new Mail::Sender {smtp => 'your.mailhost.com'};
     if ($sender->OpenMultipart({from => 'itstech2@gate.net', to => $recipients,
                           subject => 'Embedded Image Test', subtype => 'related',
                           boundary => 'boundary-test-1',
                           type => 'multipart/related'}) > 0) {
      $sender->SendFile(
             {description => 'html body',
             ctype => 'text/html; charset=us-ascii',
             encoding => '7bit',
             disposition => 'NONE',
             file => 'test.html'
       });
      $sender->SendFile(
       {description => 'ed\'s gif',
        ctype => 'image/gif',
        encoding => 'base64',
        disposition => "inline; filename=\"apache_pb.gif\";\r\nContent-ID: <ed1>",
        file => 'apache_pb.gif'
       });
      $sender->Close() or die "Close failed! $Mail::Sender::Error\n";
     } else {
      die "Cannot send mail: $Mail::Sender::Error\n";
     }
     __END__

    In the HTML you'll have this : ... <IMG src="cid:ed1"> ...

    Please keep in mind that the image name is unimportant, the
    Content-ID is what counts!

    The module was made so that you could create an object
    initialized with all the necesary options and then send several
    messages without need to specify the SMTP server and others each
    time. If you need to send only one mail using MailMsg() or
    MailFile() you do not have to create a named object and then
    call the method. You may do it like this :

     (new Mail::Sender)->MailMsg({smtp => 'mail.company.com', ...});

  WARNING

    DO NOT mix Open(Multipart)|Send(Line)(Ex)|Close with MailMsg or
    MailFile. Both Mail(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!!!

BUGS
    This module (as well as those I used as an example when I wrote
    it) doesn't work with qmail. To make this clear, the local SMTP
    server you contact directly from the script (Open({smtp =>
    ...})) may not be qmail. The problem is that the module expects
    a one-line response from the server and gets confused if it gets
    a longer response. If you set up qmail to send only one-line
    responses you shell be OK. Otherwise you need to use a different
    SMTP server. Sorry, I'll fix this as soon as I have some spare
    time.

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>

    With help of Rodrigo Siqueira <rodrigo@insite.com.br>, Ed
    McGuigan <itstech1@gate.net>, and others.

COPYRIGHT
    Copyright (c) 1997-1999 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.

