view release on metacpan or  search on metacpan

lib/Email/SendGrid/V3.pm  view on Meta::CPAN

#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<success> - Boolean indicating whether the operation returned a 2XX status code
#pod
#pod =item *
#pod
#pod C<status> - The HTTP status code of the response
#pod
#pod =item *
#pod
#pod C<reason> - The response phrase returned by the server
#pod
#pod =item *
#pod
#pod C<content> - 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});