mailtrap 1.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dee4a202b02e16f840e8fc74526903e10418a0073c2392faf964dcdbcdfcde4
-  data.tar.gz: d35cf9fa125e8ec587f96626be7830f4398002173b7dc07c4560dddbbb0ddb3e
+  metadata.gz: 7529f2a048f1670c6eb22f04a9308e17fb3072a0bcacdff87f3772e45f792201
+  data.tar.gz: bc71abbd0af5a9c79d719aaaa69671aa836ec00f3a42c1c94991605ab803494d
 SHA512:
-  metadata.gz: 5b4c0ba57ab2cab64cec15704bd34c04be134360a2600d2fc530bcae47ab8caf2e8dd79ce7ba5fd342e46dad599153d473006613c953da868182dcff2bb1e2be
-  data.tar.gz: 45d64a548b0cd54e0f98394a8c6739d1bc5dcd90716105100f7bae92f7aa5913c9ff66fde412d8965d3818bc7d6594c1c218d96cfcde59eabc6bd92c1901e2c3
+  metadata.gz: ad794ce35f915afd6ff52da55278c21146630f8f05a5f544477dbeb53c9eb7cf3277632b0f3584c909c6b3d8f2bd339c575f1d32da5065b86f88450053e716c1
+  data.tar.gz: f5b564ce76bc6d9157c5e58654cbfe54ee7f1cf169b53b2d3856ecf8fda1cd7b1fef6becc6eac2ed6bf3bbbed29eb63b8bcfb8c58fb237e37d4b68e43a78a020

data/.rubocop.yml

@@ -31,3 +31,11 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   Enabled: true
   EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - 'examples/**/*'
+
+Style/TrailingCommaInHashLiteral:
+  Exclude:
+    - 'examples/**/*'

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [2.0.0] - 2024-03-20
+
+- Added arguments for `Mailtrap::Client`
+  - `bulk` to use Mailtrap bulk sending API
+  - `sandbox` to use Mailtrap sandbox API
+  - `inbox_id` required when using Mailtrap sandbox API
+
+- Removed Sending namespace, affected classes:
+  - `Mailtrap::Sending::Client` -> `Mailtrap::Client`
+  - `Mailtrap::Sending::Error` -> `Mailtrap::Error`
+  - `Mailtrap::Sending::AttachmentContentError` -> `Mailtrap::AttachmentContentError`
+  - `Mailtrap::Sending::AuthorizationError` -> `Mailtrap::AuthorizationError`
+  - `Mailtrap::Sending::MailSizeError` -> `Mailtrap::MailSizeError`
+  - `Mailtrap::Sending::RateLimitError` -> `Mailtrap::RateLimitError`
+  - `Mailtrap::Sending::RejectionError` -> `Mailtrap::RejectionError`
+
+## [1.2.2] - 2023-11-01
+
+- Improved error handling
+
 ## [1.2.1] - 2023-04-12
 
 - Set custom user agent

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mailtrap (1.2.1)
+    mailtrap (2.0.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -6,6 +6,8 @@ This Ruby gem offers integration with the [official API](https://api-docs.mailtr
 
 Quickly add email sending functionality to your Ruby application with Mailtrap.
 
+(This client uses API v2, for v1 refer to [this documentation](https://mailtrap.docs.apiary.io/))
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -40,95 +42,35 @@ mail = Mailtrap::Mail::Base.new(
 )
 
 # create client and send
-client = Mailtrap::Sending::Client.new(api_key: 'your-api-key')
+client = Mailtrap::Client.new(api_key: 'your-api-key')
 client.send(mail)
 ```
 
-### Full
-
-```ruby
-require 'mailtrap'
-require 'base64'
-
-mail = Mailtrap::Mail::Base.new(
-  from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
-  to: [
-    { email: 'your@email.com', name: 'Your name' }
-  ],
-  cc: [
-    { email: 'cc@email.com', name: 'Copy To' }
-  ],
-  bcc: [
-    { email: 'bcc@email.com', name: 'Hidden Recipient' }
-  ],
-  subject: 'You are awesome!',
-  text: "Congrats for sending test email with Mailtrap!",
-  category: "Integration Test",
-  attachments: [
-    {
-      content: Base64.encode64('Attachment content'), # base64 encoded content or IO string
-      filename: 'attachment.txt'
-    }
-  ],
-  headers: {
-    'X-MT-Header': 'Custom header'
-  },
-  custom_variables: {
-    year: 2022
-  }
-)
-
-data = File.open('/path/to/image.jpg').read
-encoded = Base64.encode64(data).gsub(/\n/,"")
-
-mail.add_attachment(content: encoded, filename: 'image.png')
-
-client = Mailtrap::Sending::Client.new(api_key: 'your-api-key')
-client.send(mail)
-```
+Refer to the [`examples`](examples) folder for other examples.
 
-### Using email template
+- [Full](examples/full.rb)
+- [Email template](examples/email_template.rb)
+- [ActionMailer](examples/action_mailer.rb)
 
-```ruby
-require 'mailtrap'
+### Content-Transfer-Encoding
 
-# create mail object
-mail = Mailtrap::Mail::FromTemplate.new(
-  from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
-  to: [
-    { email: 'your@email.com' }
-  ],
-  template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
-  template_variables: {
-    'user_name' => 'John Doe'
-  }
-)
+`mailtrap` gem uses Mailtrap API to send emails. Mailtrap API does not try to
+replicate SMTP. That is why you should expect some limitations when it comes to 
+sending. For example, `/api/send` endpoint ignores `Content-Transfer-Encoding`
+(see `headers` in the [API documentation](https://railsware.stoplight.io/docs/mailtrap-api-docs/67f1d70aeb62c-send-email)).
+Meaning your recipients will receive emails only in the default encoding which 
+is `quoted-printable`, if you send with Mailtrap API.
 
-# create client and send
-client = Mailtrap::Sending::Client.new(api_key: 'your-api-key')
-client.send(mail)
-```
+For those who does need to use `7bit` or any other encoding, SMTP provides 
+better flexibility in that regard. Go to your _Mailtrap account_ → _Email Sending_ 
+→ _Sending Domains_ → _Your domain_ → _SMTP/API Settings_ to find the SMTP 
+configuration example.
 
-### ActionMailer
+## Migration guide v1 → v2
 
-This gem also adds ActionMailer delivery method. To configure it, add following to your ActionMailer configuration (in Rails projects located in `config/$ENVIRONMENT.rb`):
-```ruby
-config.action_mailer.delivery_method = :mailtrap
-config.action_mailer.mailtrap_settings = {
-  api_key: ENV.fetch('MAILTRAP_API_KEY')
-}
-```
-And continue to use ActionMailer as usual.
+Change `Mailtrap::Sending::Client` to `Mailtrap::Client`.
 
-To add `category` and `custom_variables`, add them to the mail generation:
-```ruby
-mail(
-  to: 'your@email.com',
-  subject: 'You are awesome!',
-  category: 'Test category',
-  custom_variables: { test_variable: 'abc' }
-)
-```
+If you use classes which have `Sending` namespace, remove the namespace like in the example above.
 
 ## Development
 

data/lib/mailtrap/action_mailer/delivery_method.rb

@@ -5,6 +5,8 @@ module Mailtrap
     class DeliveryMethod
       attr_accessor :settings
 
+      ALLOWED_PARAMS = %i[api_key api_host api_port bulk sandbox inbox_id].freeze
+
       def initialize(settings)
         self.settings = settings
       end
@@ -18,7 +20,7 @@ module Mailtrap
       private
 
       def client
-        @client ||= Mailtrap::Sending::Client.new(**settings.slice(:api_key, :api_host, :api_port))
+        @client ||= Mailtrap::Client.new(**settings.slice(*ALLOWED_PARAMS))
       end
     end
   end

data/lib/mailtrap/attachment.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+
+module Mailtrap
+  class Attachment
+    attr_accessor :type, :filename, :disposition, :content_id
+    attr_reader :content
+
+    def initialize(content:, filename:, type: nil, disposition: nil, content_id: nil)
+      self.content = content
+      @type = type
+      @filename = filename
+      @disposition = disposition
+      @content_id = content_id
+    end
+
+    def as_json
+      {
+        'content' => content,
+        'type' => type,
+        'filename' => filename,
+        'disposition' => disposition,
+        'content_id' => content_id
+      }.compact
+    end
+
+    def content=(content)
+      if content.respond_to?(:read)
+        @content = encode(content)
+      else
+        raise AttachmentContentError unless base64?(content)
+
+        @content = content
+      end
+    end
+
+    private
+
+    def encode(io)
+      string = io.read.encode('UTF-8') unless io.respond_to?(:binmode?) && io.binmode?
+      Base64.encode64(string).gsub(/\n/, '')
+    end
+
+    def base64?(string)
+      string.is_a?(String) && Base64.strict_encode64(Base64.decode64(string)) == string
+    end
+  end
+end

data/lib/mailtrap/client.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Mailtrap
+  class Client
+    SENDING_API_HOST = 'send.api.mailtrap.io'
+    BULK_SENDING_API_HOST = 'bulk.api.mailtrap.io'
+    SANDBOX_API_HOST = 'sandbox.api.mailtrap.io'
+    API_PORT = 443
+
+    attr_reader :api_key, :api_host, :api_port, :bulk, :sandbox, :inbox_id
+
+    # Initializes a new Mailtrap::Client instance.
+    #
+    # @param [String] api_key The Mailtrap API key to use for sending. Required.
+    #                         If not set, is taken from the MAILTRAP_API_KEY environment variable.
+    # @param [String, nil] api_host The Mailtrap API hostname. If not set, is chosen internally.
+    # @param [Integer] api_port The Mailtrap API port. Default: 443.
+    # @param [Boolean] bulk Whether to use the Mailtrap bulk sending API. Default: false.
+    #                       If enabled, is incompatible with `sandbox: true`.
+    # @param [Boolean] sandbox Whether to use the Mailtrap sandbox API. Default: false.
+    #                          If enabled, is incompatible with `bulk: true`.
+    # @param [Integer] inbox_id The sandbox inbox ID to send to. Required if sandbox API is used.
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      api_key: ENV.fetch('MAILTRAP_API_KEY'),
+      api_host: nil,
+      api_port: API_PORT,
+      bulk: false,
+      sandbox: false,
+      inbox_id: nil
+    )
+      raise ArgumentError, 'api_key is required' if api_key.nil?
+      raise ArgumentError, 'api_port is required' if api_port.nil?
+
+      api_host ||= select_api_host(bulk: bulk, sandbox: sandbox)
+      raise ArgumentError, 'inbox_id is required for sandbox API' if sandbox && inbox_id.nil?
+
+      @api_key = api_key
+      @api_host = api_host
+      @api_port = api_port
+      @bulk = bulk
+      @sandbox = sandbox
+      @inbox_id = inbox_id
+    end
+
+    def send(mail)
+      raise ArgumentError, 'should be Mailtrap::Mail::Base object' unless mail.is_a? Mail::Base
+
+      request = post_request(request_url, mail.to_json)
+      response = http_client.request(request)
+
+      handle_response(response)
+    end
+
+    private
+
+    def select_api_host(bulk:, sandbox:)
+      raise ArgumentError, 'bulk mode is not applicable for sandbox API' if bulk && sandbox
+
+      if sandbox
+        SANDBOX_API_HOST
+      elsif bulk
+        BULK_SENDING_API_HOST
+      else
+        SENDING_API_HOST
+      end
+    end
+
+    def request_url
+      "/api/send#{sandbox ? "/#{inbox_id}" : ""}"
+    end
+
+    def http_client
+      @http_client ||= Net::HTTP.new(api_host, api_port).tap { |client| client.use_ssl = true }
+    end
+
+    def post_request(path, body)
+      request = Net::HTTP::Post.new(path)
+      request.body = body
+      request['Authorization'] = "Bearer #{api_key}"
+      request['Content-Type'] = 'application/json'
+      request['User-Agent'] = 'mailtrap-ruby (https://github.com/railsware/mailtrap-ruby)'
+
+      request
+    end
+
+    def handle_response(response) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      case response
+      when Net::HTTPOK
+        json_response(response.body)
+      when Net::HTTPBadRequest
+        raise Mailtrap::Error, json_response(response.body)[:errors]
+      when Net::HTTPUnauthorized
+        raise Mailtrap::AuthorizationError, json_response(response.body)[:errors]
+      when Net::HTTPForbidden
+        raise Mailtrap::RejectionError, json_response(response.body)[:errors]
+      when Net::HTTPPayloadTooLarge
+        raise Mailtrap::MailSizeError, ['message too large']
+      when Net::HTTPTooManyRequests
+        raise Mailtrap::RateLimitError, ['too many requests']
+      when Net::HTTPClientError
+        raise Mailtrap::Error, ['client error']
+      when Net::HTTPServerError
+        raise Mailtrap::Error, ['server error']
+      else
+        raise Mailtrap::Error, ["unexpected status code=#{response.code}"]
+      end
+    end
+
+    def json_response(body)
+      JSON.parse(body, symbolize_names: true)
+    end
+  end
+end

data/lib/mailtrap/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'attachment'
+require_relative 'client'
+
+module Mailtrap
+  class AttachmentContentError < StandardError; end
+
+  class Error < StandardError
+    attr_reader :messages
+
+    def initialize(messages)
+      @messages = messages
+
+      super(messages.join(', '))
+    end
+  end
+
+  # AuthorizationError is raised when invalid token is used.
+  class AuthorizationError < Error; end
+
+  # MailSizeError is raised when mail is too large.
+  class MailSizeError < Error; end
+
+  # RateLimitError is raised when client performing too many requests.
+  class RateLimitError < Error; end
+
+  # RejectionError is raised when server refuses to process the request. Use
+  # error message to debug the problem.
+  #
+  # *Some* possible reasons:
+  #   * Account is banned
+  #   * Domain is not verified
+  class RejectionError < Error; end
+end

data/lib/mailtrap/mail/base.rb

@@ -59,11 +59,11 @@ module Mailtrap
       end
 
       def attachments=(attachments)
-        @attachments = attachments.map { |attachment| Mailtrap::Sending::Attachment.new(**attachment) }
+        @attachments = attachments.map { |attachment| Mailtrap::Attachment.new(**attachment) }
       end
 
       def add_attachment(content:, filename:, type: nil, disposition: nil, content_id: nil)
-        attachment = Mailtrap::Sending::Attachment.new(
+        attachment = Mailtrap::Attachment.new(
           content: content,
           filename: filename,
           type: type,

data/lib/mailtrap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailtrap
-  VERSION = '1.2.1'
+  VERSION = '2.0.0'
 end

data/lib/mailtrap.rb

@@ -2,7 +2,7 @@
 
 require_relative 'mailtrap/action_mailer' if defined? ActionMailer
 require_relative 'mailtrap/mail'
-require_relative 'mailtrap/sending'
+require_relative 'mailtrap/errors'
 require_relative 'mailtrap/version'
 
 module Mailtrap; end

data/mailtrap.gemspec

@@ -23,7 +23,9 @@ Gem::Specification.new do |spec|
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|github|travis|circleci)|appveyor)})
+      (f == __FILE__) || f.match(
+        %r{\A(?:(?:bin|test|spec|features|examples)/|\.(?:git|github|travis|circleci)|appveyor)}
+      )
     end
   end
   spec.require_paths = ['lib']

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-13 00:00:00.000000000 Z
+date: 2024-03-28 00:00:00.000000000 Z
 dependencies: []
 description: Official mailtrap.io API client
 email:
@@ -32,12 +32,12 @@ files:
 - lib/mailtrap/action_mailer.rb
 - lib/mailtrap/action_mailer/delivery_method.rb
 - lib/mailtrap/action_mailer/railtie.rb
+- lib/mailtrap/attachment.rb
+- lib/mailtrap/client.rb
+- lib/mailtrap/errors.rb
 - lib/mailtrap/mail.rb
 - lib/mailtrap/mail/base.rb
 - lib/mailtrap/mail/from_template.rb
-- lib/mailtrap/sending.rb
-- lib/mailtrap/sending/attachment.rb
-- lib/mailtrap/sending/client.rb
 - lib/mailtrap/version.rb
 - mailtrap.gemspec
 homepage: https://github.com/railsware/mailtrap-ruby
@@ -63,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Official mailtrap.io API client

data/lib/mailtrap/sending/attachment.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-require 'base64'
-require 'json'
-
-module Mailtrap
-  module Sending
-    class Attachment
-      attr_accessor :type, :filename, :disposition, :content_id
-      attr_reader :content
-
-      def initialize(content:, filename:, type: nil, disposition: nil, content_id: nil)
-        self.content = content
-        @type = type
-        @filename = filename
-        @disposition = disposition
-        @content_id = content_id
-      end
-
-      def as_json
-        {
-          'content' => content,
-          'type' => type,
-          'filename' => filename,
-          'disposition' => disposition,
-          'content_id' => content_id
-        }.compact
-      end
-
-      def content=(content)
-        if content.respond_to?(:read)
-          @content = encode(content)
-        else
-          raise AttachmentContentError unless base64?(content)
-
-          @content = content
-        end
-      end
-
-      private
-
-      def encode(io)
-        string = io.read.encode('UTF-8') unless io.respond_to?(:binmode?) && io.binmode?
-        Base64.encode64(string).gsub(/\n/, '')
-      end
-
-      def base64?(string)
-        string.is_a?(String) && Base64.strict_encode64(Base64.decode64(string)) == string
-      end
-    end
-  end
-end

data/lib/mailtrap/sending/client.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'net/http'
-require 'uri'
-
-module Mailtrap
-  module Sending
-    class Client
-      API_HOST = 'send.api.mailtrap.io'
-      API_PORT = 443
-
-      attr_reader :api_key, :api_host, :api_port
-
-      def initialize(api_key: ENV.fetch('MAILTRAP_API_KEY'), api_host: API_HOST, api_port: API_PORT)
-        @api_key = api_key
-        @api_host = api_host
-        @api_port = api_port
-      end
-
-      def send(mail)
-        raise ArgumentError, 'should be Mailtrap::Mail::Base object' unless mail.is_a? Mail::Base
-
-        request = post_request('/api/send', mail.to_json)
-        response = http_client.request(request)
-
-        handle_response(response)
-      end
-
-      private
-
-      def http_client
-        @http_client ||= Net::HTTP.new(api_host, api_port).tap { |client| client.use_ssl = true }
-      end
-
-      def post_request(path, body)
-        request = Net::HTTP::Post.new(path)
-        request.body = body
-        request['Authorization'] = "Bearer #{api_key}"
-        request['Content-Type'] = 'application/json'
-        request['User-Agent'] = 'mailtrap-ruby (https://github.com/railsware/mailtrap-ruby)'
-
-        request
-      end
-
-      def handle_response(response)
-        case response.code
-        when '200'
-          json_response(response.body)
-        when '400'
-          raise Mailtrap::Sending::Error, json_response(response.body)[:errors]
-        when '401'
-          raise Mailtrap::Sending::AuthorizationError, json_response(response.body)[:errors]
-        else
-          raise Mailtrap::Sending::Error, ['server error']
-        end
-      end
-
-      def json_response(body)
-        JSON.parse(body, symbolize_names: true)
-      end
-    end
-  end
-end

data/lib/mailtrap/sending.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'sending/attachment'
-require_relative 'sending/client'
-
-module Mailtrap
-  module Sending
-    class AttachmentContentError < StandardError; end
-
-    class Error < StandardError
-      attr_reader :messages
-
-      def initialize(messages)
-        @messages = messages
-
-        super(messages.join(', '))
-      end
-    end
-
-    class AuthorizationError < Error; end
-  end
-end