view release on metacpan or  search on metacpan

lib/Amazon/SES.pm  view on Meta::CPAN

use Moops;

# ABSTRACT: Interfaces with AWS's SES service.

class Amazon::SES  {
    use strict;
    use warnings;
    use Carp ('croak');
    use MIME::Base64;
    use Time::Piece;
    use HTTP::Headers;
    use LWP::UserAgent;
    use AWS::Signature4;
    use Amazon::SES::Response;
    use VM::EC2::Security::CredentialCache;
    use HTTP::Request::Common;
    use Kavorka qw( multi method );



    has 'ua' => (is => 'ro', default => sub { return LWP::UserAgent->new() } );
    has 'use_iam_role' => ( is => 'ro', default => 0 );
    has 'access_key'   => ( is => 'ro' );
    has 'secret_key'   => ( is => 'ro' );
    has 'region'       => ( is => 'ro', default => 'us-east-1' );
    has 'response'       => ( is => 'rw' );
    

    method call(Str $action, HashRef $args? = {}) {
        $args->{AWSAccessKeyId} = $self->access_key;
        $args->{Action}         = $action;
        
        my $request = POST("https://email." . $self->region . ".amazonaws.com", $args);
        
        if ($self->{use_iam_role}) {
            my $creds = VM::EC2::Security::CredentialCache->get();
            defined($creds) || die("Unable to retrieve IAM role credentials");
            $self->{access_key} = $creds->accessKeyId;
            $self->{secret_key} = $creds->secretAccessKey;
            $request->header('x-amz-security-token' => $creds->sessionToken);
        }
        
        
        # Add the signature.
        my $signer = AWS::Signature4->new(-access_key => $self->access_key,
                                          -secret_key => $self->secret_key);
        $signer->sign($request);
        
        my $response = $self->ua->request($request);
        return Amazon::SES::Response->new(response => $response, 
                                          action => $action );
    }

    multi method send(MIME::Entity $message) {
        $self->send_mime($message);
    }

    multi method send(Str :$from,
                      Str :$body?,
                      Str :$body_html?,
                      Str :$to,
                      Str :$subject?,
                      Str :$charset = "UTF-8",
                      Str :$return_path?,
                  ) {
        $to = [$to] unless ref($to);
        defined($body) || defined($body_html) || die("No body specified");
        my %call_args = (
            'Message.Subject.Data'    => $subject,
            'Message.Subject.Charset' => $charset,
            'Source'                  => $from
        );
        
        if (defined($body)) {
            $call_args{'Message.Body.Text.Data'} = $body;
            $call_args{'Message.Body.Text.Charset'} = $charset;
        }
        
        
        if (defined($body_html)) {
            $call_args{'Message.Body.Html.Data'} = $body_html;
            $call_args{'Message.Body.Html.Charset'} = $charset;
        }

        if (defined($return_path)) {
            $call_args{'ReturnPath'} = $return_path;
        }
        my $i = 1;
        map { 
            $call_args{'Destination.ToAddresses.member.' . $i++} = $_;
        } @$to;
        
        $self->call( 'SendEmail', \%call_args );
    }
    
    
    method verify_email(Str $email) {

lib/Amazon/SES.pm  view on Meta::CPAN

    method send_mime(Str|MIME::Entity $message) {
        my $src = $message;
        if (ref($message) && $message->isa("MIME::Entity") ) {
            $src = $message->stringify;
        } 
        
        return $self->call( 'SendRawEmail',
                            { 'RawMessage.Data' => MIME::Base64::encode_base64($src) } );
    }
    
    method get_dkim_attributes(Str @identities) {
        my %call_args  = ();
        my $i =1 ;
        map { 
            $call_args{'Identities.member.' . $i++} = $_;
        } @identities;
        return $self->call( 'GetIdentityDkimAttributes', \%call_args );
    }
    
}

1;

__END__

=head1 NAME

Amazon::SES - Perl extension that implements Amazon Simple Email Service (SES) client

=head1 SYNOPSIS

    use Amazon::SES;

    my $ses = Amazon::SES->new(access_key => '....', secret_key => '...');
    # or
    my $ses = Amazon::SES->new(use_iam_role => 1);

    my $r = $ses->send(
        From    => '[your SES identity]',
        To      => '[recipient]',
        Subject => 'Hello World from SES',
        Body    => "Hello World"
    );

    unless ( $r->is_success ) {
        die "Could not deliver the message: " . $r->error_message;
    }

    printf("Sent successfully. MessageID: %s\n", $r->message_id);

    ######### sending attachments
    my $msg = MIME::Entity->build();
    my $r = $ses->send( $msg );

=head1 DESCRIPTION

Implements Amazon Web Services' Simple Email Service (SES). Sess L<http://docs.aws.amazon.com/ses/latest/DeveloperGuide/Welcome.html> for details and to sign-up for the service.  Forked from Net::AWS::SES, changed to use Moops and updated to support ...

=head1 GETTING STARTED

After you sign-up for AWS SES service you need to create an C<IAM> credentials and create an C<access_key> and a C<secret_key>, which you will be needing to interface with the SES. Do not forget to grant permission to your C<IAM> to use SES. Read L<h...

=head1 METHODS

I attempted to make the method names as Perlish as possible, as opposed to direct copy/paste from the API reference. This way I felt you didn't have to be familiar with the full API reference in order to use the basic features of the service.

If you are avid AWS developer there is a C<call()> method, which gives you access to all the documented Query actions of the AWS SES. In fact, that's what all the methods use to hide the complexity of the request/response. There are few examples of t...

All the methods (including C<call()>) returns an instance of L<Response|Amazon::SES::Response>. You should check if the the call is success by testing for C<is_success> attribute of the response. If you want to gain full access to the raw parsed cone...

=head2 new(access_key => $key, secret_key => $s_key)

=head2 new(access_key => $key, secret_key => $s_key, region => $region)

=head2 new(use_iam_role => 1)

Returns a Amazon::SES instance. C<access_key> and C<secret_key> arguments are optional if not specifying to C<use_iam_role>. C<region> is optional, and can be overriden in respective api calls. Must be a valid SES region: C<us-east-1>, C<us-west-2> o...

=head2 send( $msg )

=head2 send(%options)

Sends an email address and returns L<Response|Amazon::SES::Response> instance.

If the only argument is passed, it must be an instance of MIME::Entity. Example:

    $msg = MIME::Entity->build(
        from    => '[your address]',
        to      => '[your recipient]',
        subject => 'MIME msg from AWS SES',
        data    => "<h1>Hello world from AWS SES</h1>",
        type    => 'text/html'
    );

    $msg->attach(
        Path     => File::Spec->catfile( 't', 'image.gif' ),
        Type     => 'image/gif',
        Encoding => 'base64'
    );

    $ses = Amazon::SES->new(....);
    $r = $ses->send($msg);

    unless ( $r->is_success ) {
        die $r->error_message;
    }

If you don't have MIME::Entity instance handy you may use the following arguments to have AWS SES build the message for you (bold entries are required): C<From>, B<To>, B<Subject>, B<Body>, C<Body_html>, C<ReturnPath>. To send e-mail to multiple emai...

If C<From> is missing it defaults to your default e-mail given to C<new()>. Remember: this must be a verified e-mail. Example:

    $r = $ses->send(
        from    => '[your email address]',
        to      => '[destination email address]',
        subject => 'Hello World'
        body    => 'Hello World'
    );
    unless ( $r->is_success ) {
        die $r->error_message;
    }