NAME
Mojo::SMTP::Client - SMTP client based on Mojo::IOLoop
SYNOPSIS
# blocking
my $smtp = Mojo::SMTP::Client->new(address => '10.54.17.28', autodie => 1);
$smtp->send(
from => 'me@from.org',
to => 'you@to.org',
data => join("\r\n", 'From: me@from.org',
'To: you@to.org',
'Subject: Hello world!',
'',
'This is my first message!'
),
quit => 1
);
warn "Sent successfully"; # else will throw exception because of `autodie'# non-blocking
my $smtp = Mojo::SMTP::Client->new(address => '10.54.17.28');
$smtp->send(
from => 'me@from.org',
to => 'you@to.org',
data => join("\r\n", 'From: me@from.org',
'To: you@to.org',
'Subject: Hello world!',
'',
'This is my first message!'
),
quit => 1,
sub {
my ($smtp, $resp) = @_;
warn $resp->{error} ? 'Failed to send: '.$resp->{error} : 'Sent successfully';
Mojo::IOLoop->stop;
}
);
Mojo::IOLoop->start;DESCRIPTION
With Mojo::SMTP::Client you can easily send emails from your Mojolicious application without blocking of Mojo::IOLoop.
EVENTS
Mojo::SMTP::Client inherits all events from Mojo::EventEmitter and can emit the following new ones
response
$smtp->on(response => sub {
my ($smtp, $cmd, $resp) = @_;
});Emitted for each SMTP response from the server. $cmd is a command constant for which this response was sent. For $resp description see "send".
ATTRIBUTES
Mojo::SMTP::Client implements the following attributes, which you can set in the constructor or get/set later with object method call
address
Address for SMTP server (ip or domain name). Default is localhost
port
Port for SMTP server. Default is 25
hello
SMTP requires that you identify yourself. This option specifies a string to pass as your mail domain. Default is localhost.localdomain
connect_timeout
Maximum amount of time in seconds establishing a connection may take before getting canceled, defaults to the value of the MOJO_CONNECT_TIMEOUT environment variable or 10
inactivity_timeout
Maximum amount of time in seconds a connection can be inactive before getting closed, defaults to the value of the MOJO_INACTIVITY_TIMEOUT environment variable or 20. Setting the value to 0 will allow connections to be inactive indefinitely
ioloop
Event loop object to use for blocking I/O operations, defaults to a Mojo::IOLoop object
autodie
Defines should Mojo::SMTP::Client throw exceptions for any type of errors. This only usable for blocking usage of Mojo::SMTP::Client, because non-blocking one should never die. Throwed exception will be one of the specified in Mojo::SMTP::Client::Exception. When autodie attribute has false value you should check $resp>{error} yourself.
METHODS
Mojo::SMTP::Client inherits all methods from Mojo::EventEmitter and implements the following new ones
send
$smtp->send(
from => $mail_from,
to => $rcpt_to,
data => $data,
quit => 1,
$nonblocking ? $cb : ()
);Send specified commands to SMTP server. Arguments should be key => value pairs where key is a command and value is a value for this command. send understands the following commands:
- from
-
From which email this message was sent. Value for this cammand should be a string with email
$smtp->send(from => 'root@cpan.org'); - to
-
To which email(s) this message should be sent. Value for this cammand should be a string with email or reference to array with email strings (for more than one recipient)
$smtp->send(to => 'oleg@cpan.org'); $smtp->send(to => ['oleg@cpan.org', 'do_not_reply@cpantesters.org']); - data
-
Email body to be sent. Value for this command should be a string with email body or reference to subroutine each call of which should return some chunk of the email as tring and empty string at the end (useful to send big emails in memory efficient way)
$smtp->send(data => "Subject: This is my first message\r\n\r\nSent from Mojolicious app"); $smtp->send(data => sub { sysread(DATA, my $buf, 1024); $buf }); - quit
-
Send
QUITcommand to SMTP server which will close the connection. So for the next use of this server connection will be reestablished. If you want to send several emails with this server it will be more efficient to not quit the connection until last email will be sent.
For non-blocking usage last argument to send should be reference to subroutine which will be called when result will be available. Subroutine arguments will be ($smtp, $resp). Where $resp is reference to a hash with response. This hash may has this keys: error, code, messages. First you should check error - if it has true value this means that it was error somewhere while sending. $resp->{error} will be one of Mojo::SMTP::Client::Exception::* objects defined in Mojo::SMTP::Client::Exception. If error has false value you can get code and messages for last command with $resp->{code} (number) and $resp->{messages} (reference to array with strings).
For blocking usage $resp will be returned as result of $smtp->send call. $resp is the same as for non-blocking result. If "autodie" attribute has true value send will throw an exception on any error. Which will be one of Mojo::SMTP::Client::Exception::*.
Note. Connection to SMTP server will be made on first send or for each send when socket connection not already estabilished (was closed by QUIT command or errors in the stream). It is error to make several simultaneous non-blocking send calls on the same Mojo::SMTP::Client, because each client has one global stream per client. So, you need to create several clients to make simultaneous sending.
CONSTANTS
Mojo::SMTP::Client has this non-importable constants
CMD_CONNECT # client connected to SMTP server
CMD_EHLO # client sent EHLO command
CMD_HELO # client sent HELO command
CMD_FROM # client sent MAIL FROM command
CMD_TO # client sent RCPT TO command
CMD_DATA # client sent DATA command
CMD_DATA_END # client sent . command
CMD_QUIT # client sent QUIT commandSEE ALSO
Mojo::SMTP::Client::Exception, Mojolicious, Mojo::IOLoop
COPYRIGHT
Copyright Oleg G <oleg@cpan.org>.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.