Nile::Plugin::Email

# NAME

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

# SYNOPSIS

            $email = $me->plugin->email;
            # or create new object
            #$email = $me->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',
                    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`.

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