amply-ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4277fb080efe8030459c1e5c6f837738b224e368ace142d33875a41926cf8f7e
+  data.tar.gz: fbd25ca786496e8dba524ea98cc4c5bce9c650200201a0f1a1286da0d6e18f89
+SHA512:
+  metadata.gz: 76066fdb26b96a85bb8628f29585e855113459ffaff974262f0ffce09eedf2fb20e637c31661e50d414b7e537e6e64bc2acba2cfd11fd11efd4eda3502b00fa6
+  data.tar.gz: 07b11ae389c464c513413734743f53fd912e8d9a0469e28629b181a0d2d65cdc5d36599ce776115242cc93cd50fb249dbacf5891b48b1d7b389e9297fd7e8e22

data/.gitignore

@@ -0,0 +1,5 @@
+*.swp
+.DS_Store
+*.log
+.idea/
+*.gem

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2020, Send Amply Inc. <support@sendamply.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,107 @@
+# Amply
+
+This is the Amply Ruby SDK that integrates with the [v1 API](https://docs.sendamply.com/docs/api/docs/Introduction.md).
+
+__Table of Contents__
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Classes](#classes)
+	- [Email](#Email)
+
+## Install
+
+### Prerequisites
+- Ruby 2.4+
+- Amply account, [sign up here.](https://sendamply.com/plans)
+
+### Access Token
+
+Obtain your access token from the [Amply UI.](https://sendamply.com/home/settings/access_tokens)
+
+### Install Package
+```
+gem install amply-ruby
+```
+
+### Domain Verification
+Add domains you want to send `from` via the [Verified Domains](https://sendamply.com/home/settings/verified_domains) tab on your dashboard.
+
+Any emails you attempt to send from an unverified domain will be rejected.  Once verified, Amply immediately starts warming up your domain and IP reputation.  This warmup process will take approximately one week before maximal deliverability has been reached.
+
+## Quick Start
+The following is the minimum needed code to send a simple email. Use this example, and modify the `to` and `from` variables:
+
+```ruby
+require 'amply'
+  
+Amply.set_access_token(ENV['AMPLY_ACCESS_TOKEN'])
+
+begin
+  Amply::Email.create(to: 'test@example.com',
+                      from: 'test@verifieddomain.com',
+                      subject: 'My first Amply email!',
+                      text: 'This is easy',
+                      html: '<strong>and fun :)</strong>')
+
+rescue Amply::Exceptions::APIException => e
+  # Most likely invalid access token
+  puts e.status
+  puts e.text
+rescue Amply::Exceptions::ValidationException => e
+  puts e.message
+  puts e.errors
+end
+```
+
+Once you execute this code, you should have an email in the inbox of the recipient.  You can check the status of your email in the UI from the [Search](https://sendamply.com/home/analytics/searches/basic/new), [SQL](https://sendamply.com/home/analytics/searches/sql/new), or [Users](https://sendamply.com/home/analytics/users) page.
+
+## Methods
+
+### email
+
+Parameter(s)         | Description
+:---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+to, cc, bcc | Email address of the recipient(s).  This may be a string `Test <test@example.com>`, a hash `{ name: 'Test', email: 'test@example.com' }`, or an array of strings and hashes.
+personalizations | For fine tuned access, you may override the to, cc, and bcc keys and use advanced personalizations.  See the API guide [here](https://docs.sendamply.com/docs/api/Mail-Send.v1.yaml/paths/~1email/post).
+from | Email address of the sender.  This may be formatted as a string or hash.  An array of senders is not allowed.
+subject | Subject of the message.
+html | HTML portion of the message.
+text | Text portion of the message.
+content | An array of hashes containing the following keys: `type` (required), `value` (required).
+template | The template to use. This may be a string (the UUID of the template), an array of UUID's (useful for A/B/... testing where one is randomly selected), or a hash of the format `{ template1Uuid: 0.25, template2Uuid: 0.75 }` (useful for weighted A/B/... testing).
+dynamic_template_data | The dynamic data to be replaced in your template.  This is an hash of the format `{ variable1: 'replacement1', ... }`. Variables should be defined in your template body as `${variable1}`.
+reply_to |Email address of who should receive replies.  This may be a string or a hash with `name` and `email` keys.
+headers | A hash where the header name is the key and header value is the value.
+ip_or_pool_uuid | The UUID of the IP address or IP pool you want to send from.  Default is your Global pool.
+unsubscribe_group_uuid | The UUID of the unsubscribe group you want to associate with this email.
+attachments[][content] | A base64 encoded string of your attachment's content.
+attachments[][type] | The MIME type of your attachment.
+attachments[][filename] | The filename of your attachment.
+attachments[][disposition] | The disposition of your attachment (`inline` or `attachment`).
+attachments[][content_id] | The content ID of your attachment.
+clicktracking | Enable or disable clicktracking.
+categories | An array of email categories you can associate with your message.
+substitutions | A hash of the format `{ sub_from: 'sub_to', ...}` of substitutions.
+
+__Example__
+
+```ruby
+Amply::Email.create(to:   'example@test.com',
+                    from: 'From <example@verifieddomain.com>',
+                    text: 'Text part',
+                    html: 'HTML part',
+                    personalizations: [{ to: [{ name: 'Override To', email: 'test@example.com' }] }],
+                    content: [{ type: 'text/testing', value: 'some custom content type' }],
+                    subject: 'A new email!',
+                    reply_to: 'Reply To <test@example.com>',
+                    template: 'faecb75b-371e-4062-89d5-372b8ff0effd',
+                    dynamic_template_data: { name: 'Jimmy' },
+                    unsubscribe_group_uuid: '5ac48b43-6e7e-4c51-817d-f81ea0a09816',
+                    ip_or_pool_uuid: '2e378fc9-3e23-4853-bccb-2990fda83ca9',
+                    attachments: [{'content': 'dGVzdA==', 'filename': 'test.txt', 'type': 'text/plain', 'disposition': 'inline'}],
+                    headers: {'X-Testing': 'Test'},
+                    categories: ['Test'],
+                    clicktracking: true,
+                    substitutions: { sub1: 'replacement1' })
+```

data/amply-ruby.gemspec

@@ -0,0 +1,21 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'amply/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'amply-ruby'
+  spec.version     = Amply::VERSION
+  spec.email       = 'support@sendamply.com'
+  spec.authors     = ['Amply']
+  spec.summary     = 'Amply Gem'
+  spec.description = 'Amply Gem to Interact with Amply\'s API in native Ruby'
+  spec.homepage    = 'https://github.com/sendamply/amply-ruby'
+
+  spec.required_ruby_version = '>= 2.4'
+
+  spec.license = 'MIT'
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(/^bin/) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)/)
+  spec.require_paths = ['lib']
+end

data/lib/amply/client.rb

@@ -0,0 +1,55 @@
+require 'net/http'
+require 'json'
+
+module Amply
+  class Client
+    DEFAULT_HEADERS = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json'
+    }
+
+    class << self
+      @@access_token = ''
+      @@url          = 'https://sendamply.com/api/v1'
+
+      def set_access_token(token)
+        @@access_token = token
+      end
+
+      def post(path, body, options = {})
+        uri = URI("#{@@url}#{path}")
+        headers = [
+          DEFAULT_HEADERS,
+          options[:headers] || {},
+          auth_header
+        ].inject(&:merge)
+
+
+        resp = Net::HTTP.post(uri, body.to_json, headers)
+        parse_response(resp)
+      end
+
+      def parse_response(resp)
+        code = resp.code.to_i
+
+        if [301, 302].include?(code)
+          return resp['location']
+        elsif [401, 403].include?(code)
+          raise Exceptions::APIException, resp
+        elsif code == 404
+          raise Exceptions::ResourcNotFoundException, resp
+        elsif code == 422
+          raise Exceptions::ValidationException, resp
+        elsif code < 200 || code >= 300
+          raise Exceptions::APIException, resp
+        end
+
+        JSON.parse(resp.body, symbolize_names: true)
+      end
+
+      def auth_header
+        { Authorization: "Bearer #{@@access_token}" }
+      end
+    end
+  end
+end

data/lib/amply/email.rb

@@ -0,0 +1,12 @@
+require_relative './helpers/email'
+
+module Amply
+  class Email
+    class << self
+      def create(data)
+        parsed_data = Helpers::Email.new(data).parsed_data
+        Client.post('/email', parsed_data)
+      end
+    end
+  end
+end

data/lib/amply/exceptions/api_exception.rb

@@ -0,0 +1,18 @@
+module Amply
+  module Exceptions
+    class APIException < StandardError
+      attr_reader :status, :text
+
+      def initialize(response)
+        @status = response.code.to_i
+        @text = response.message
+
+        super
+      end
+
+      def message
+        'An error occurred while making an API request'
+      end
+    end
+  end
+end

data/lib/amply/exceptions/resource_not_found_exception.rb

@@ -0,0 +1,19 @@
+require 'json'
+
+module Amply
+  module Exceptions
+    class ResourceNotFoundException < StandardError
+      attr_reader :errors
+
+      def initialize(response)
+        @errors = JSON.parse(response.body, symbolize_names: true)[:errors]
+
+        super
+      end
+
+      def message
+        'The resource was not found while making an API request'
+      end
+    end
+  end
+end

data/lib/amply/exceptions/validation_exception.rb

@@ -0,0 +1,19 @@
+require 'json'
+
+module Amply
+  module Exceptions
+    class ValidationException < StandardError
+      attr_reader :errors
+
+      def initialize(response)
+        @errors = JSON.parse(response.body, symbolize_names: true)[:errors]
+
+        super
+      end
+
+      def message
+        'A validation error occurred while making an API request'
+      end
+    end
+  end
+end

data/lib/amply/exceptions.rb

@@ -0,0 +1,3 @@
+require_relative './exceptions/api_exception'
+require_relative './exceptions/validation_exception'
+require_relative './exceptions/resource_not_found_exception'

data/lib/amply/helpers/email.rb

@@ -0,0 +1,247 @@
+require 'json'
+
+require_relative './email_address'
+
+module Amply
+  module Helpers
+    class Email
+      def initialize(data)
+        @data = data
+        @request_data = {}
+      end
+
+      def parsed_data
+        unless @data.is_a?(Hash)
+          raise 'Expecting hash for email data'
+        end
+
+        data_sym = JSON.parse(JSON.dump(@data), symbolize_names: true)
+
+        set_from(data_sym[:from])
+        set_subject(data_sym[:subject])
+        set_text(data_sym[:text])
+        set_html(data_sym[:html])
+        set_content(data_sym[:content])
+        set_reply_to(data_sym[:reply_to])
+        set_template(data_sym[:template])
+        set_dynamic_template_data(data_sym[:dynamic_template_data])
+        set_unsubscribe_group_uuid(data_sym[:unsubscribe_group_uuid])
+        set_ip_or_pool_uuid(data_sym[:ip_or_pool_uuid])
+        set_attachments(data_sym[:attachments])
+        set_headers(data_sym[:headers])
+        set_categories(data_sym[:categories])
+        set_clicktracking(data_sym[:clicktracking])
+        set_substitutions(data_sym[:substitutions])
+
+        if data_sym[:personalizations].nil?
+          set_personalizations_from_to(data_sym[:to], data_sym[:cc], data_sym[:bcc])
+        else
+          set_personalizations(data_sym[:personalizations])
+        end
+
+        @request_data
+      end
+
+      private
+
+      def set_from(from)
+        return if from.nil?
+        @request_data[:from] = format_emails(from)[0]
+      end
+
+      def set_subject(subject)
+        unless subject.is_a?(String)
+          raise 'String expected for `subject`'
+        end
+
+        @request_data[:subject] = subject
+      end
+
+      def set_text(text)
+        return if text.nil?
+
+        @request_data[:content] ||= []
+        @request_data[:content].push(type: 'text/plain', value: text)
+      end
+
+      def set_html(html)
+        return if html.nil?
+
+        @request_data[:content] ||= []
+        @request_data[:content].push(type: 'text/html', value: html)
+      end
+
+      def set_content(content)
+        return if content.nil?
+
+        unless content.is_a?(Array)
+          raise 'Array expected for `content`'
+        end
+
+        @request_data[:content] ||= []
+
+        content.each_with_index do |part, i|
+          unless part.is_a?(Hash)
+            raise "Hash expected for `content[#{i}]`"
+          end
+
+          type = part[:type] || part['type']
+          value = part[:value] || part['value']
+
+          if type.nil?
+            raise "`type` must be defined for `content[#{i}][type]`"
+          end
+
+          if value.nil?
+            raise "`value` must be defined for `content[#{i}][type]`"
+          end
+
+          @request_data[:content].push(type: type, value: value)
+        end
+      end
+
+      def set_reply_to(reply_to)
+        return if reply_to.nil?
+        @request_data[:reply_to] = format_emails(reply_to)[0]
+      end
+
+      def set_template(template)
+        return if template.nil?
+        @request_data[:template] = template
+      end
+
+      def set_dynamic_template_data(dynamic_template_data)
+        return if dynamic_template_data.nil?
+
+        unless dynamic_template_data.is_a?(Hash)
+          raise 'Hash expected for `dynamic_template_data`'
+        end
+
+        @request_data[:substitutions] ||= {}
+
+        dynamic_template_data.each do |sub_from, sub_to|
+          @request_data[:substitutions]["${#{sub_from}}"] = sub_to.to_s
+        end
+      end
+
+      def set_unsubscribe_group_uuid(unsubscribe_group_uuid)
+        return if unsubscribe_group_uuid.nil?
+        @request_data[:unsubscribe_group_uuid] = unsubscribe_group_uuid
+      end
+
+      def set_ip_or_pool_uuid(ip_or_pool_uuid)
+        return if ip_or_pool_uuid.nil?
+        @request_data[:ip_or_pool_uuid] = ip_or_pool_uuid
+      end
+
+      def set_attachments(attachments)
+        return if attachments.nil?
+
+        unless attachments.is_a?(Array)
+          raise 'Array expected for `attachments`'
+        end
+
+        @request_data[:attachments] ||= []
+
+        attachments.each_with_index do |attachment, i|
+          unless attachment.is_a?(Hash)
+            raise "Hash expected for `attachments[#{i}]`"
+          end
+
+          content     = attachment[:content] || attachment['content']
+          filename    = attachment[:filename] || attachment['filename']
+          type        = attachment[:type] || attachment['type']
+          disposition = attachment[:disposition] || attachment['disposition']
+
+          if content.nil?
+            raise "`content` must be defined for `attachments[#{i}][content]`"
+          end
+
+          if filename.nil?
+            raise "`filename` must be defined for `attachments[#{i}][filename]`"
+          end
+
+          data = { content: content, filename: filename }
+          data.merge!(type: type) unless type.nil?
+          data.merge!(disposition: disposition) unless disposition.nil?
+
+          @request_data[:attachments].push(data)
+        end
+      end
+
+      def set_headers(headers)
+        return if headers.nil?
+
+        unless headers.is_a?(Hash)
+          raise 'Hash expected for `headers`'
+        end
+
+        @request_data[:headers] ||= {}
+
+        headers.each do |name, value|
+          @request_data[:headers][name] = value.to_s
+        end
+      end
+
+      def set_categories(categories)
+        return if categories.nil?
+
+        unless categories.is_a?(Array)
+          raise 'Array expected for `categories`'
+        end
+
+        @request_data[:analytics] ||= {}
+        @request_data[:analytics][:categories] = categories.map { |category| category.to_s }
+      end
+
+      def set_clicktracking(clicktracking)
+        return if clicktracking.nil?
+
+        unless [TrueClass, FalseClass].include?(clicktracking.class)
+          raise 'Expecting TrueClass or FalseClass for `clicktracking`'
+        end
+
+        @request_data[:analytics] ||= {}
+        @request_data[:analytics][:clicktracking] = clicktracking
+      end
+
+      def set_substitutions(substitutions)
+        return if substitutions.nil?
+
+        unless substitutions.is_a?(Hash)
+          raise 'Hash expected for `substitutions`'
+        end
+
+        @request_data[:substitutions] ||= {}
+
+        substitutions.each do |sub_from, sub_to|
+          @request_data[:substitutions][sub_from] = sub_to.to_s
+        end
+      end
+
+      def set_personalizations_from_to(to, cc, bcc)
+        @request_data[:personalizations] = [{}]
+
+        if to.nil? && cc.nil? && bcc.nil?
+          raise 'Provide at least one of `to`, `cc` or `bcc`'
+        end
+
+        @request_data[:personalizations][0][:to] = format_emails(to) unless to.nil?
+        @request_data[:personalizations][0][:cc] = format_emails(cc) unless cc.nil?
+        @request_data[:personalizations][0][:bcc] = format_emails(bcc) unless bcc.nil?
+      end
+
+      def set_personalizations(personalizations)
+        @request_data[:personalizations] = personalizations
+      end
+
+      def format_emails(emails)
+        if emails.is_a?(Array)
+          return emails.map { |email| EmailAddress.new(email).to_json }
+        end
+
+        [EmailAddress.new(emails).to_json]
+      end
+    end
+  end
+end

data/lib/amply/helpers/email_address.rb

@@ -0,0 +1,84 @@
+module Amply
+  module Helpers
+    class EmailAddress
+      class << self
+        def create(data)
+          if data.is_a?(Array)
+            return data.reject { |el| el.nil? || el == '' }
+              .map { |el| self.class.create(el) }
+          end
+
+          if data.is_a?(EmailAddress)
+            return data
+          end
+
+          self.class.create(data)
+        end
+      end
+
+      def initialize(data)
+        if data.is_a?(String)
+          data = from_string(data)
+        end
+
+        unless data.is_a?(Hash)
+          raise 'Expecting hash or string for email address data'
+        end
+
+        name = data[:name] || data['name']
+        email = data[:email] || data['email']
+
+        set_name(name)
+        set_email(email)
+      end
+
+      def to_json
+        json = { email: @email }
+
+        unless @name.nil?
+          json[:name] = @name
+        end
+
+        json
+      end
+
+      private
+
+      def set_name(name)
+        return if name.nil?
+
+        unless name.is_a?(String)
+          raise 'String expected for `name`'
+        end
+
+        @name = name
+      end
+
+      def set_email(email)
+        if email.nil?
+          raise 'Must provide `email`'
+        end
+
+        unless email.is_a?(String)
+          raise 'String expected for `email`'
+        end
+
+        @email = email
+      end
+
+      def from_string(data)
+        if data.index('<').nil?
+          return { name: nil, email: data }
+        end
+
+        name, email = data.split('<')
+
+        name.strip!
+        email.gsub!('>', '')
+        email.strip!
+
+        { name: name, email: email }
+      end
+    end
+  end
+end

data/lib/amply/version.rb

@@ -0,0 +1,3 @@
+module Amply
+  VERSION = '0.0.1'
+end

data/lib/amply.rb

@@ -0,0 +1,12 @@
+require_relative 'amply/version'
+require_relative 'amply/exceptions'
+require_relative 'amply/client'
+require_relative 'amply/email'
+
+module Amply
+  class << self
+    def set_access_token(token)
+      Client.set_access_token(token)
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: amply-ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Amply
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-12-28 00:00:00.000000000 Z
+dependencies: []
+description: Amply Gem to Interact with Amply's API in native Ruby
+email: support@sendamply.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- LICENSE
+- README.md
+- amply-ruby.gemspec
+- lib/amply.rb
+- lib/amply/client.rb
+- lib/amply/email.rb
+- lib/amply/exceptions.rb
+- lib/amply/exceptions/api_exception.rb
+- lib/amply/exceptions/resource_not_found_exception.rb
+- lib/amply/exceptions/validation_exception.rb
+- lib/amply/helpers/email.rb
+- lib/amply/helpers/email_address.rb
+- lib/amply/version.rb
+homepage: https://github.com/sendamply/amply-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.7.6
+signing_key:
+specification_version: 4
+summary: Amply Gem
+test_files: []