The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Nile-0.55
River stage zero No dependents
2 ++
/ Nile::Plugin::Email

NAME

Nile::Plugin::Email - Email plugin for the Nile framework.

SYNOPSIS

    $email = $app->plugin->email;
    # or create new object
    #$email = $app->plugin->email->new;

    $email->email({
        from    => 'ahmed@mewsoft.com',
        to      => 'ramy@domain.com',
        subject => 'Happy birthday Ramy',
        body    => 'Hello Ramy, Happy new year Ramy',
        type    => 'html', # 'html' or 'text' message type
        attach  => '/path/to/attachment', # optional attachment file
    });

DESCRIPTION

Nile::Plugin::Email - Email plugin for the Nile framework.

This plugin build on the top of Email::Sender::Simple module which supports any transporter like Sendmail, SMTP etc.

Plugin configuration can be set in the config file under the plugin section.

Example plugin configuration for SMTP transporter:

    <plugin>

        <email>
            <transport>SMTP</transport>
            <host>localhost</host>
            <ssl>0</ssl>
            <port>25</port>
            <timeout>120</timeout>
            <sasl_username></sasl_username>
            <sasl_password>0</sasl_password>
            <allow_partial_success>0</allow_partial_success>
            <helo>Hello from loclahost</helo>
            <localaddr>localhost</localaddr>
            <localport>1234</localport>
        </email>

    </plugin>

Example plugin configuration for Sendmail transporter:

    <plugin>

        <email>
            <transport>Sendmail</transport>
            <sendmail>/usr/sbin/sendmail</sendmail>
        </email>

    </plugin>

If no configuration found, the module will search for Sendmail program and use it, if not found it will try to connect to local SMTP server.

You also can set the transporter programmatically using the method "transport" below.

email()

Send email with optional attachments quickly:

    $email->email({
        from    => 'ahmed@mewsoft.com',
        #from    => '"Ahmed Elsheshtawy" <ahmed@mewsoft.com>',
        to      => 'ramy@domain.com',
        subject => 'Happy birthday Ramy',
        body    => 'Hello Ramy, Happy new year Ramy',
        type    => 'html', # 'html' or 'text' message type, default 'html'
        attach  => '/path/to/attachment',   # optional attachment file
    });

Send email with many options:

    $email->email({

        from        => 'ahmed@mewsoft.com',
        to      => 'ramy@ramys.net',

        cc      => ['x@y.com', 'a@b.com', 'b@d.com'],
        bcc     => ['c@x.com', 'e@z.com', 'r@j.com'],

        subject => 'Happy birthday Ramy',
        
        # optional headers
        sender      => 'support@mewsoft.com', # set to the 'from' if not set
        #'Return-Path'  =>  '', # set to the 'from' if not set
        #'Reply-To'     =>  '', # set to the 'from' if not set
        #'X-Mailer'     =>  'Nile',
        #'X-Priority'   =>  3, # highest => 1, high => 2, normal => 3, low => 4, lowest => 5
        #Date       =>  email_date(), # automatically set to current date and time
        #Comments   =>  '',
        #Encrypted  =>  '',
        #References     =>  '',
        #'Message-ID'   =>  '',
        #'MIME-Version' =>  '',
        #Organization   =>  'Mewsoft',
        
        #multipart  => 'related',

        type        => 'html', # 'html' or 'text' message type, default 'html'

        # optional raw headers overried above and used as is
        header      => {
            "X-Mailer"          => '',
            "X-Accept-Language" => 'en',
        },
        
        # attachments
        attach      => [
            '/path/to/attachment1', 
            '/path/to/attachment2',
            '/path/to/attachment3',
            {
                Path => "/path/to/attachment4",
                # Mime::Entity options.
                Id => "...",
            }
        ],
    });

Set the email components one by one for more control:

    $email->from('ahmed@mewsoft.com');
    $email->to('x@domain.com');
    $email->cc(['a@b.com', 'b@c.com']);
    $email->bcc(['d@e.com', 'e@f.com']);
    $email->sender('company@mewsoft.com');
    $email->type('text');
    $email->mailer('Nile');
    $email->subject('Happy birthday');
    $email->body('Hello Ramy, Happy new year');
    
    # send the email
    $email->send();

from()

    $email->from('ahmed@mewsoft.com');
    $from = $email->from;

Sets or returns the from email address.

to()

    $email->to('ahmed@mewsoft.com');
    $to = $email->to;

Sets or returns the to email address.

sender()

    # if not set, the from address will be used
    $email->sender('support@mewsoft.com');
    $sender = $email->sender;

Sets or returns the sender email address.

cc()

    $email->cc('x@mewsoft.com', 'y@mewsoft.com');
    @cc = $email->cc;

Sets or returns the cc email addresses.

bcc()

    $email->bcc('x@mewsoft.com', 'y@mewsoft.com');
    @bcc= $email->bcc;

Sets or returns the bcc email addresses.

subject()

    $email->subject($subject);
    $subject = $email->subject;

Sets or returns the subject.

body()

    $email->body($body);
    $body = $email->body;

Sets or returns the body.

encoding()

    # default is 'quoted-printable'
    $email->encoding($encoding);
    $encoding = $email->encoding;

Sets or returns the encoding. Standard encodings are '7bit', '8bit', 'base64', 'binary', 'quoted-printable'. Non-standard encodings are 'binhex', 'binhex40', 'mac-binhex40', 'mac-binhex', 'x-uu', 'x-uuencode'.

Encoding auto detected if not set.

format()

    # $format = 'flowed';
    $email->format($format);
    $format = $email->format;

Sets or returns the format.

charset()

    # default $charset = "UTF-8";
    $email->charset($charset);
    $charset = $email->charset;

Sets or returns the charset.

multipart()

    # default is "mixed" for "multipart/mixed"
    $email->multipart("mixed");
    $multipart = $email->multipart;

Sets or returns the multipart.

header()

    $email->header->{$name} = $value;
    $value = $email->header->{$name};

Sets or returns the header entries.

type()

    # html email message
    $email->type("html");
    
    # text/plain email message
    $email->type("text");

Sets or returns the message content type.

mailer()

    $email->mailer("Nile");

Sets or returns the header X-Mailer.

attach()

    $email->attach('/path/to/attachment1');
    $email->attach('/path/to/attachment2');

    $email->attach(
        '/path/to/attachment1',
        '/path/to/attachment2',
        '/path/to/attachment3',
        {
            Path => "/path/to/attachment4",
            # Mime::Entity options
            Id => "...",
        }
    );

Attach files to the email message.

transport()

    $email->transport($transport, %options);
    
    # set transport to Sendmail program, path auto detected
    $email->transport('Sendmail');

    # set transport to Sendmail program, specify path to it
    $email->transport('Sendmail', { sendmail => '/usr/sbin/sendmail' });
    
    # set transport to SMTP with options
    $email->transport("SMTP", {
        host => 'mail.mewsoft.com', # the name of the host to connect to; defaults to localhost
        ssl => 0, # if true, connect via SSL; defaults to false
        port => 25, # port to connect to; defaults to 25 for non-SSL, 465 for SSL
        timeout => 180, # maximum time in secs to wait for server; default is 120
        sasl_username => '', # the username to use for auth; optional
        sasl_password => '', # the password to use for auth; required if username is provided
        allow_partial_success => 0, # if true, will send data even if some recipients were rejected; defaults to false
        helo => 'mail.mewsoft.com', # what to say when saying HELO; no default
        #localaddr => 'localhost', # local address from which to connect
        #localport =>'1234', # local port from which to connect
    });
    
    # custom transport
    #$transport = MyTransport->new();
    $email->transport($transport, %options);

Set the email transporter class. Can be Email::Sender::Transport subclass name like Sendmail, SMTP, etc or Email::Sender::Transport type object.

To find available transporters, search cpan for Email::Sender::Transport

send()

    $email->send();

Send the email with current settings. This method is called automatically by the method email to send the email.

Bugs

This project is available on github at https://github.com/mewsoft/Nile.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Nile.

SOURCE

Source repository is at https://github.com/mewsoft/Nile.

SEE ALSO

See Nile for details about the complete framework.

AUTHOR

Ahmed Amin Elsheshtawy, احمد امين الششتاوى <mewsoft@cpan.org> Website: http://www.mewsoft.com

COPYRIGHT AND LICENSE

Copyright (C) 2014-2015 by Dr. Ahmed Amin Elsheshtawy احمد امين الششتاوى mewsoft@cpan.org, support@mewsoft.com, https://github.com/mewsoft/Nile, http://www.mewsoft.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.