Author image Waldemar Biernacki
and 1 contributors

NAME

    Mail::Sendmail::Enhanced v.0.03 - Pure Perl email sender with multibyte characters encoding and easy attachments managment

SYNOPSIS

  #!/usr/bin/perl -w

  use strict;
  use warnings;

  use Mail::Sendmail::Enhanced;

  # This part simulate the general setup of application mailer.
  # It sets smtp server and size limit of attachments (1MB)
  # This configuration is set by admin.
  my $mail = Mail::Sendmail::Enhanced-> new(
    charset     => 'cp1250',
    smtp        => 'Your SMTP server',
    from        => 'Your mail',
    user        => 'user',
    pass        => 'password',
    method      => 'LOGIN',
    required    => 1,
    attachments => {
      'name for email of the file1' => 'OS file1 location',
      'name for email of the file2' => 'OS file2 location',
    },
    attachments_size_max => '1MB',
    commit      => 0,
  );

  # This part simulate how clients can use the mailer.
  # Configuration here is set by clients themself.
  my @client = qw(John Henry Newman);
  for (@client) {

    my $lowercase = chr(185).chr(230).chr(234).chr(179).chr(241).chr(243).chr(156).chr(159).chr(191);
    my $uppercase = chr(165).chr(198).chr(202).chr(163).chr(209).chr(211).chr(140).chr(143).chr(175);

    print $mail-> send( {
      to    => 'author of the module: <wb@webswing.co.uk>',
      subject  => "Subject longer than 80 characters with Polish letters: lowercase: $lowercase and uppercase: $uppercase.",
      message  => "This is the message from $_ in the character encoding ".$mail->{charset}.".

      This is an example of mailing Polish letters in a header field named \"Subject\".
      Additionally this field is longer than 80 characters.

      Additional text:
      Polish lowercase letters: $lowercase
      Polish uppercase letters: $uppercase
      ",
    });
  }

  __END__

DESCRIPTION

Mail::Sendmail::Enhanced is an enhanced version of the module Mail::Sendmail. It is still pure Perl solution. In the module the problem of encoding multibyte characters in Mail::Sendmail was solved. Some procedure of sending very easily a list of attachments was prepared.

After preparing multibyte characters encoding and building message with attachments the module calls sendmail function from the Mail::Sendmail module which does all the job.So please read there in Mail::Sendmail about how to set up connections to email servers. This module behaves identically.

As already mentioned this adds two things:

1. Multibyte characters encoding - which uses refurbish and imported function encode_qp from the module MIME::QuotedPrint::Perl.

The problem with encoding multibyte characters was that simple implemented encoding - especially in the "Subject:" field of email header - results that some characters are divided between two rows when long lines are folded. Some email clients are not able to put together these separated bytes into one character and letters are displeyed inproperly. The new encoding function keeps bytes of one character in one folded row.

2. Simple attachments managment. List of attachments is a hash:

  attachments => {
    'name for email of the file1' => 'OS file1 location',
    'name for email of the file2' => 'OS file2 location',
  },

where the keys are the attachments email names and the values are OS locations.

It is possible to add some control to sending attachment. It is done by the parameter attachments_size_max. Possible values are:

  attachments_size_max => -1,         # Negative value means that sending attachments is forbidden.
                                      # Every try of sending them with this value negative is fatal one.

  attachments_size_max =>  0,         # No size limit of attachments

  attachments_size_max => '50 000 B', # Positive value is a maximum size of attachment.
                                      # When size is bigger then fatal error is return.
                                      # Spaces and the letter B (byte) are ignored.

                                      # shorthand for sizes: k, K, m, M:
  attachments_size_max => '100k',     # k = 1000,         so maximum =   100 000
  attachments_size_max => '100 K',    # K = 1024,         so maximum =   102 400
  attachments_size_max => '2 m',      # m = 1000x1000,    so maximum = 1 000 000
  attachments_size_max => '2M',       # M = 1024x1024,    so maximum = 1 048 576

INTERFACE

Interface Mail::Sendmail::Enhanced, gets two methods:

new()

The method new creates mail object.

send()

The method send sends mail.

Arguments of both methods are the same and discussed earlier. Dispersing data between new and send is fully optional. Assuming that we have three hashes %n, %s and %d which fullfiled the abstract equality:

    "%n + %s = %d"

all the three ways of sending email have the same effect:

    1. my $mail = Mail::Sendmail::Enhanced->new(%n); $mail->send(%s);

    2. my $mail = Mail::Sendmail::Enhanced->new(); $mail->send(%d);

    3. my $mail = Mail::Sendmail::Enhanced->new(%d); $mail->send();

This third way can be replaced by only one call with additional argument "commit" with the value 1 (look back at the SYNOPSIS):

    commit => 1,

in that case email is sent at the end of the method new.

BUGS

Please report any bugs or feature requests to bug-mail-sendmail-enhanced at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mail-Sendmail-Enhanced. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

LICENSE AND COPYRIGHT

Copyright (C) 2015 Waldemar Biernacki, <wb at webswing.co.uk>

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO

Mail::Sendmail, MIME::QuotedPrint::Perl