/ 
Nile-0.43
River stage zero No dependents
/ 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.