File Coverage

blib/lib/Email/SendGrid/V3.pm

Criterion	Covered	Total	%
statement	86	254	33.8
branch	25	144	17.3
condition	7	42	16.6
subroutine	17	48	35.4
pod	37	37	100.0
total	172	525	32.7

package Email::SendGrid::V3;

our $AUTHORITY = 'cpan:GSG';
# ABSTRACT: Class for building a message to be sent through the SendGrid v3 Web API
use version;
our $VERSION = 'v0.900.1'; # VERSION

use v5.10.1;
use strict;
use warnings;

use Carp;
use JSON;
use HTTP::Tiny;

use constant DEFAULT_ENDPOINT => 'https://api.sendgrid.com/v3/mail/send';

use namespace::clean;  # don't export the above

#pod =encoding utf8
#pod
#pod =head1 SYNOPSIS
#pod
#pod     use Email::SendGrid::V3;
#pod
#pod     my $sg = Email::SendGrid::V3->new(api_key => 'XYZ123');
#pod
#pod     my $result = $sg->from('[e-mail]')
#pod                     ->subject('A test message for you')
#pod                     ->add_content('text/plain', 'This is a test message sent with SendGrid')
#pod                     ->add_envelope( to => [ '[e-mail]' ] )
#pod                     ->send;
#pod
#pod     print $result->{success} ? "It worked" : "It failed: " . $result->{reason};
#pod
#pod =head1 DESCRIPTION
#pod
#pod This module allows for easy integration with the SendGrid email distribution
#pod service and its v3 Web API.  All instance methods are chainable.
#pod
#pod For the full details of the SendGrid v3 API, see L
#pod
#pod =head1 CLASS METHODS
#pod
#pod =head2 Creation
#pod
#pod =head3 new(%args)
#pod
#pod Creates a new Email::SendGrid object.  Optional param: 'api_key'
#pod
#pod =cut

sub new {
    my ($class, %args) = @_;
    $class = ref($class) || $class;

    my $self = bless +{
        %args,
        data => {},
    }, $class;

    return $self;
}

#pod =head1 INSTANCE METHODS
#pod
#pod =head2 Sending / Validating
#pod
#pod =head3 send(%args)
#pod
#pod Sends the API request and returns a result hashref with these keys:
#pod
#pod =over 4
#pod
#pod =item *
#pod
#pod C - Boolean indicating whether the operation returned a 2XX status code
#pod
#pod =item *
#pod
#pod C - The HTTP status code of the response
#pod
#pod =item *
#pod
#pod C - The response phrase returned by the server
#pod
#pod =item *
#pod
#pod C - The body of the response, including a detailed error message, if any.
#pod
#pod =back
#pod
#pod =cut

sub send {
    my ($self, %args) = @_;
    my $api_key = $args{api_key} || $self->{api_key} or croak "API key is required to send";
    my $endpoint = $args{endpoint} || $self->{endpoint} || DEFAULT_ENDPOINT;
    my $payload = $self->_payload;

    my $http = HTTP::Tiny->new(
        keep_alive => 0,
        default_headers => {
            'Content-Type' => 'application/json',
            'Authorization' => "Bearer $api_key",
        },
    );

    my $response = $http->post(
        $endpoint, { content => $payload },
    );

    return $response;
}

#pod =head3 validate(%args)
#pod
#pod Temporarily sets the 'sandbox_mode' flag to true, and submits the API request
#pod to SendGrid.  Returns the same hashref format as send().  If the 'success' key
#pod is true, the API request is valid.
#pod
#pod =cut

sub validate {
    my ($self, %args) = @_;

    local $self->{data}{mail_settings}{sandbox_mode} = { enable => JSON::true };

    return $self->send(%args);
}

sub _payload {
    my ($self) = @_;
    return JSON->new->utf8->canonical->encode( $self->{data} );
}

#pod =head2 Personalizations / Envelopes
#pod
#pod =head3 $self->add_envelope(%args);
#pod
#pod Once you've defined the general message parameters (by setting from, content, etc)
#pod You must add at least one envelope.  Each envelope represents one personalized copy
#pod of a message, and who should receive it.  Some parameters can only be set at the message
#pod level, some only at the envelope level, and some at both (the envelop-level settings will
#pod override the message-level settings).
#pod
#pod You must specify at least the 'to' argument, which is an array of recipient emails.  This
#pod can be a plain array of addresses, or an array of hashes with 'email' and 'name' keys.
#pod
#pod The 'cc' and 'bcc' arguments are optional, but follow the same format of the 'to' argument.
#pod
#pod In addition to specifying the envelope recipients via to/cc/bcc, you can also override the
#pod message 'subject', 'send_at', 'headers' hash, 'substitutions' hash, and 'custom_args' hash.
#pod See the message-level methods for more details on those parameters.
#pod
#pod =cut

sub add_envelope {
    my ($self, %args) = @_;

    my $to = _standardize_recips('to', $args{to});
    my $cc = _standardize_recips('cc', $args{cc});
    my $bcc = _standardize_recips('bcc', $args{bcc});

    croak "Envelope must include at least one 'to' address" unless @$to;

    my $envelope = { to => $to };
    $envelope->{cc} = $cc if @$cc;
    $envelope->{bcc} = $bcc if @$bcc;

    $envelope->{subject} = $args{subject} if $args{subject};
    $envelope->{send_at} = $args{send_at} if $args{send_at};

    if ($args{headers}) {
        croak "Envelope headers must be a hashref" unless ref $args{headers} eq 'HASH';
        $envelope->{headers} = $args{headers};
    }

    if ($args{substitutions}) {
        croak "Envelope substitutions must be a hashref" unless ref $args{substitutions} eq 'HASH';
        $envelope->{substitutions} = $args{substitutions};
    }

    if ($args{dynamic_template_data}) {
        croak "Envelope dynamic_template_data must be a hashref" unless ref $args{dynamic_template_data} eq 'HASH';
        $envelope->{dynamic_template_data} = $args{dynamic_template_data};
    }

    if ($args{custom_args}) {
        croak "Envelope custom args must be a hashref" unless ref $args{custom_args} eq 'HASH';
        $envelope->{custom_args} = $args{custom_args};
    }

    $self->{data}{personalizations} ||= [];

    push @{ $self->{data}{personalizations} }, $envelope;

    return $self;
}

sub _standardize_recips {
    my ($name, $data) = @_;
    my $reftype = ref $data;

    return [] unless $data;

    if (! $reftype) {
        $data = [$data];
    }
    elsif ($reftype eq 'HASH') {
        $data = [$data];
    }
    elsif ($reftype ne 'ARRAY') {
        croak "Envelope $name must be an array";
    }

    my @return;
    foreach my $recip (@$data) {
        next unless $recip;

        my $recipreftype = ref $recip;

        if (! $recipreftype) {
            push @return, {
                email => $recip,
            };
        }
        elsif ($recipreftype eq 'HASH') {
            push @return, $recip;
        }
        else {
            croak "Invalid envelope $name";
        }
    }

    return \@return;
}

#pod =head3 $self->clear_envelopes();
#pod
#pod Clears all of the currently defined envelopes from this message.
#pod
#pod =cut

sub clear_envelopes {
    my ($self) = @_;

    delete $self->{data}{personalizations};

    return $self;
}

#pod =head2 Messages
#pod
#pod =head3 $self->from($email, $name);
#pod
#pod Sets the name/email address of the sender.
#pod Email is required, name is optional.
#pod
#pod =cut

sub from {
    my ($self, $email, $name) = @_;

    croak "From email is required" unless $email;

    $self->{data}{from} = { email => $email };
    $self->{data}{from}{name} = $name if $name;

    return $self;
}

#pod =head3 $self->subject($subject);
#pod
#pod Sets the subject of the message.
#pod Required, but can be overridden at the message personalization level.
#pod
#pod =cut

sub subject {
    my ($self, $subject) = @_;

    croak "Subject is required" unless $subject;

    $self->{data}{subject} = $subject;

    return $self;
}

#pod =head3 $self->reply_to($email, $name);
#pod
#pod Sets the target that will be used if the recipient wants to reply to this message.
#pod Email is required, name is optional.
#pod
#pod =cut

sub reply_to {
    my ($self, $email, $name) = @_;

    croak "Reply-to email is required" unless $email;

    $self->{data}{reply_to} = { email => $email };
    $self->{data}{reply_to}{name} = $name if $name;

    return $self;
}

#pod =head3 $self->clear_content();
#pod
#pod Clears out all of the message body parts.
#pod
#pod =cut

sub clear_content {
    my ($self) = @_;

    delete $self->{data}{content};

    return $self;
}

#pod =head3 $self->add_content($type, $value);
#pod
#pod Adds a message body part. Both type and value are required.
#pod $type should be something like "text/plain" or "text/html".
#pod
#pod =cut

sub add_content {
    my ($self, $type, $value) = @_;

    croak "Content type and value are required" unless $type && $value;

    $self->{data}{content} ||= [];

    push @{ $self->{data}{content} }, {
        type => $type,
        value => $value,
    };

    return $self;
}

#pod =head3 $self->clear_attachments();
#pod
#pod Removes all attachments from this message.
#pod
#pod =cut

sub clear_attachments {
    my ($self) = @_;

    delete $self->{data}{attachments};

    return $self;
}

#pod =head3 $self->add_attachment($filename, $content, %args);
#pod
#pod Adds a new attachment to this message.  $filename specifies the file name the recipient will see.
#pod $content should be the Base64-encoded data of the file. Optional arguments are 'type' (the mime type
#pod of the file, such as "image/jpeg"), 'disposition' must be "inline" or "attachment", and 'content_id'
#pod which is used to identify embedded inline attachments.
#pod
#pod =cut

sub add_attachment {
    my ($self, $filename, $content, %args) = @_;

    croak "Attachment filename and content are required" unless $filename && $content;

    my $new_attachment = {
        filename => $filename,
        content => $content,
    };

    $new_attachment->{type} = $args{type} if $args{type};
    $new_attachment->{disposition} = $args{disposition} if $args{disposition};
    $new_attachment->{content_id} = $args{content_id} if $args{content_id};

    $self->{data}{attachments} ||= [];
    push @{ $self->{data}{attachments} }, $new_attachment;

    return $self;
}

#pod =head3 $self->template_id($template_id);
#pod
#pod Specifies the template you'd like to use for this message.  Templates are managed via the
#pod SendGrid application website.  If the template includes a subject or body, those do not need
#pod to be specified via this api.
#pod
#pod =cut

sub template_id {
    my ($self, $template_id) = @_;

    delete $self->{data}{template_id};
    $self->{data}{template_id} = $template_id if $template_id;

    return $self;
}

#pod =head3 $self->clear_sections();
#pod
#pod Clears all substitution sections defined in this message.
#pod
#pod =cut

sub clear_sections {
    my ($self) = @_;

    delete $self->{data}{sections};

    return $self;
}

#pod =head3 $self->remove_section($key);
#pod
#pod Removes one substitution section defined in this message.
#pod
#pod =cut

sub remove_section {
    my ($self, $key) = @_;

    croak "Section key name is required" unless $key;

    delete $self->{data}{sections}{$key};

    return $self;
}

#pod =head3 $self->set_section($key, $value);
#pod
#pod Sets one new substitution section for this message.  Each occurrence of $key
#pod in each body part will be replaced with $value prior to personalization
#pod substitutions (if any).
#pod
#pod =cut

sub set_section {
    my ($self, $key, $value) = @_;

    croak "Section key name is required" unless $key;

    $self->{data}{sections} ||= {};
    $self->{data}{sections}{$key} = $value;

    return $self;
}

#pod =head3 $self->set_sections(%sections);
#pod
#pod Sets all substitution sections for this message at once.  For each key/val pair,
#pod occurrences of the key in the message body will be replaced by the value prior to
#pod personalization substitutions (if any).
#pod
#pod =cut

sub set_sections {
    my ($self, %sections) = @_;

    delete $self->{data}{sections};
    $self->{data}{sections} = \%sections if %sections;

    return $self;
}

#pod =head3 $self->clear_headers();
#pod
#pod Clears all custom headers defined for this message.
#pod
#pod =cut

sub clear_headers {
    my ($self) = @_;

    delete $self->{data}{headers};

    return $self;
}

#pod =head3 $self->set_headers(%headers);
#pod
#pod Sets all custom SMTP headers for this message at once. These must be properly encoded
#pod if they contain unicode characters. Must not be one of the reserved headers.
#pod
#pod These can be overridden at the message personalization level.
#pod
#pod =cut

sub set_headers {
    my ($self, %headers) = @_;

    delete $self->{data}{headers};
    $self->{data}{headers} = \%headers if %headers;

    return $self;
}

#pod =head3 $self->clear_categories();
#pod
#pod Clears out all categories defined for this message.
#pod
#pod =cut

sub clear_categories {
    my ($self) = @_;

    delete $self->{data}{categories};

    return $self;
}

#pod =head3 $self->set_categories(@categories);
#pod
#pod Sets the list of categories for this message.  The list of categories must be
#pod unique and contain no more than 10 items.
#pod
#pod =cut

sub set_categories {
    my ($self, @categories) = @_;

    croak "Cannot set more than 10 categories"
        if scalar( @categories ) > 10;

    delete $self->{data}{categories};

    $self->{data}{categories} = \@categories if @categories;

    return $self;
}

#pod =head3 $self->add_category($name);
#pod
#pod Adds a new category for this message.  The list of categories must be
#pod unique and contain no more than 10 items.
#pod
#pod =cut

sub add_category {
    my ($self, $name) = @_;

    croak "Category name is required" unless $name;

    $self->{data}{categories} ||= [];

    croak "Cannot add more than 10 categories"
        if scalar( @{ $self->{data}{categories} } ) > 9;

    push @{ $self->{data}{categories} }, $name;

    return $self;
}

#pod =head3 $self->clear_custom_args();
#pod
#pod Clears out all custom arguments defined for this message.
#pod
#pod =cut

sub clear_custom_args {
    my ($self) = @_;

    delete $self->{data}{custom_args};

    return $self;
}

#pod =head3 $self->set_custom_args(%args);
#pod
#pod Sets all custom arguments defined for this message.
#pod These can be overridden at the message personalization level.
#pod The total size of custom arguments cannot exceed 10,000 bytes.
#pod
#pod =cut

sub set_custom_args {
    my ($self, %args) = @_;

    delete $self->{data}{custom_args};

    $self->{data}{custom_args} = \%args if %args;

    return $self;
}

#pod =head3 $self->send_at($timestamp);
#pod
#pod A unix timestamp (seconds since 1970) specifying when to deliver this message.
#pod Cannot be more than 72 hours in the future.
#pod
#pod This can be overridden at the message personalization level.
#pod
#pod =cut

sub send_at {
    my ($self, $timestamp) = @_;

    delete $self->{data}{send_at};
    $self->{data}{send_at} = $timestamp if $timestamp;

    return $self;
}

#pod =head3 $self->batch_id($batch_id);
#pod
#pod Identifies a batch to include this message in.  This batch ID can later be used
#pod to pause or cancel the delivery of a batch (if a future delivery time was set)
#pod
#pod =cut

sub batch_id {
    my ($self, $batch_id) = @_;

    delete $self->{data}{batch_id};
    $self->{data}{batch_id} = $batch_id if $batch_id;

    return $self;
}

#pod =head3 $self->unsubscribe_group($group_id, @display_groups);
#pod
#pod If you've set up multiple unsubscribe groups in the SendGrid web application, this method
#pod allows you to specify which group this message belongs to.  If this is set and the user
#pod unsubscribes from this message, they will only be added to the suppression list for that
#pod single group.  If not set, they will be added to the global unsubscribe list.
#pod
#pod @display_groups is optional. If specified, when the user clicks "unsubscribe" they will be
#pod shown a list of these groups and allowed to choose which ones he/she would like to unsubscribe
#pod from.
#pod
#pod =cut

sub unsubscribe_group {
    my ($self, $group_id, @display_groups) = @_;

    croak "Unsubscribe group ID is required" unless $group_id;
    croak "Cannot display more than 25 groups" if scalar(@display_groups) > 25;

    $self->{data}{asm} = { group_id => $group_id };
    $self->{data}{asm}{groups_to_display} = \@display_groups if @display_groups;

    return $self;
}

#pod =head3 $self->ip_pool_name($pool_name);
#pod
#pod The IP Pool that you would like to send this email from.
#pod
#pod =cut

sub ip_pool_name {
    my ($self, $pool_name) = @_;

    delete $self->{data}{ip_pool_name};
    $self->{data}{ip_pool_name} = $pool_name if $pool_name;

    return $self;
}

#pod =head3 $self->click_tracking($enable, %args);
#pod
#pod Whether to enable click-tracking for this message.  If enabled, any URLs in the body of this
#pod message will be rewritten to proxy through SendGrid for tracking purposes.  This setting will
#pod overwrite the account-level setting if any.  One optional argument is accepted: 'enable_text'
#pod which controls whether the link-rewriting is also performed for plaintext emails (the rewritten
#pod URL will be visible to the recipient)
#pod
#pod =cut

sub click_tracking {
    my ($self, $enable, %args) = @_;

    $enable = $enable ? JSON::true : JSON::false;

    $self->{data}{tracking_settings} ||= {};
    $self->{data}{tracking_settings}{click_tracking} = { enable => $enable };

    if (defined $args{enable_text}) {
        $self->{data}{tracking_settings}{click_tracking}{enable_text} =
            $args{enable_text} ? JSON::true : JSON::false;
    }

    return $self;
}

#pod =head3 $self->open_tracking($enable, %args);
#pod
#pod Whether to enable open-tracking for this message.  If enabled, a single transparent pixel image
#pod is added to the HTML body of this message and used to determine if and when the recipient opens
#pod the message.  This setting will overwrite the account-level setting if any.  One optional argument
#pod is accepted: 'substitution_tag' which identifies a token in the message body that should be replaced
#pod with the tracking pixel.
#pod
#pod =cut

sub open_tracking {
    my ($self, $enable, %args) = @_;

    $enable = $enable ? JSON::true : JSON::false;

    $self->{data}{tracking_settings} ||= {};
    $self->{data}{tracking_settings}{open_tracking} = { enable => $enable };
    $self->{data}{tracking_settings}{open_tracking}{substitution_tag} =
        $args{substitution_tag} if $args{substitution_tag};

    return $self;
}

#pod =head3 $self->subscription_tracking($enable, %args);
#pod
#pod Whether to enable a sendgrid-powered unsubscribe link in the footer of the email.  You may pass
#pod optional arguments 'text' and 'html' to control the verbiage of the unsubscribe link used, OR
#pod 'substitution_tag' which is a token that will be replaced with the unsubscribe URL.
#pod This setting will overwrite the account-level setting if any.
#pod
#pod =cut

sub subscription_tracking {
    my ($self, $enable, %args) = @_;

    $enable = $enable ? JSON::true : JSON::false;

    my $new = { enable => $enable };
    $new->{text} = $args{text} if $args{text};
    $new->{html} = $args{html} if $args{html};
    $new->{substitution_tag} = $args{substitution_tag} if $args{substitution_tag};

    $self->{data}{tracking_settings} ||= {};
    $self->{data}{tracking_settings}{subscription_tracking} = $new;

    return $self;
}

#pod =head3 $self->ganalytics($enable, %args);
#pod
#pod Whether to enable google analytics tracking for this message.  Optional arguments
#pod include 'utm_source', 'utm_medium', 'utm_term', 'utm_content', and 'utm_campaign'.
#pod This setting will overwrite the account-level setting if any.
#pod
#pod =cut

sub ganalytics {
    my ($self, $enable, %args) = @_;

    $enable = $enable ? JSON::true : JSON::false;

    my $new = { enable => $enable };
    $new->{utm_source}     = $args{utm_source} if $args{utm_source};
    $new->{utm_medium}     = $args{utm_medium} if $args{utm_medium};
    $new->{utm_term}       = $args{utm_term} if $args{utm_term};
    $new->{utm_content}    = $args{utm_content} if $args{utm_content};
    $new->{utm_campaign}   = $args{utm_campaign} if $args{utm_campaign};

    $self->{data}{tracking_settings} ||= {};
    $self->{data}{tracking_settings}{ganalytics} = $new;

    return $self;
}

#pod =head3 $self->bcc($enable, %args);
#pod
#pod Whether to BCC a monitoring account when sending this message.  Optional arguments
#pod include 'email' for the address that will receive the BCC if one is not configured
#pod at the account level.  This setting will overwrite the account-level setting if any.
#pod
#pod =cut

sub bcc {
    my ($self, $enable, %args) = @_;

    $enable = $enable ? JSON::true : JSON::false;

    $self->{data}{mail_settings} ||= {};
    $self->{data}{mail_settings}{bcc} = { enable => $enable };
    $self->{data}{mail_settings}{bcc}{email} = $args{email} if $args{email};

    return $self;
}

#pod =head3 $self->bypass_list_management($enable);
#pod
#pod Whether to bypass the built-in suppression SendGrid provides, such as unsubscribed
#pod recipients, those that have bounced, or marked the emails as spam.
#pod This setting will overwrite the account-level setting if any.
#pod
#pod =cut

sub bypass_list_management {
    my ($self, $enable, %args) = @_;

    $enable = $enable ? JSON::true : JSON::false;

    $self->{data}{mail_settings} ||= {};
    $self->{data}{mail_settings}{bypass_list_management} = { enable => $enable };

    return $self;
}

#pod =head3 $self->footer($enable, %args);
#pod
#pod Whether to add a footer to the outgoing message. Optional arguments include 'html' and
#pod 'text' to specify the footers that will be used for each message body type.
#pod This setting will overwrite the account-level setting if any.
#pod
#pod =cut

sub footer {
    my ($self, $enable, %args) = @_;

    $enable = $enable ? JSON::true : JSON::false;

    $self->{data}{mail_settings} ||= {};
    $self->{data}{mail_settings}{footer} = { enable => $enable };
    $self->{data}{mail_settings}{footer}{text} = $args{text} if $args{text};
    $self->{data}{mail_settings}{footer}{html} = $args{html} if $args{html};

    return $self;
}

#pod =head3 $self->sandbox_mode($enable);
#pod
#pod Whether to enable sandbox mode.  When enabled, SendGrid will validate the contents of this
#pod API request for correctness, but will not actually send the message.
#pod
#pod =cut

sub sandbox_mode {
    my ($self, $enable, %args) = @_;

    $enable = $enable ? JSON::true : JSON::false;

    $self->{data}{mail_settings} ||= {};
    $self->{data}{mail_settings}{sandbox_mode} = { enable => $enable };

    return $self;
}

#pod =head3 $self->spam_check($enable, %args);
#pod
#pod Whether to perform a spam check on this message prior to sending.  If the message fails the
#pod spam check, it will be dropped and not sent.  Optional parameters include 'threshold' - an
#pod integer score value from 1-10 (default 5) over which a message will be classified as spam,
#pod and 'post_to_url' - a SendGrid inbound message parsing URL that will be used to post back
#pod notifications of messages identified as spam and dropped.  These settings will overwrite
#pod the account-level settings if any.
#pod
#pod =cut

sub spam_check {
    my ($self, $enable, %args) = @_;

    $enable = $enable ? JSON::true : JSON::false;

    $self->{data}{mail_settings} ||= {};
    $self->{data}{mail_settings}{spam_check} = { enable => $enable };
    $self->{data}{mail_settings}{spam_check}{threshold} = $args{threshold} if $args{threshold};
    $self->{data}{mail_settings}{spam_check}{post_to_url} = $args{post_to_url} if $args{post_to_url};

    return $self;
}

1;

__END__