mailtrap 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c959ed779f29713f1c7cb977d5037b6ab184e3841ad79a77450fb92bf6d21a05
-  data.tar.gz: 8fa5d1112e6fa683227bd6b00b2e538dccae08edf2894c1d8f8f275aa247e42e
+  metadata.gz: a5d46743b2ae7145ba69ca1b276417baa829601436e84653ce38ba0154a3dde5
+  data.tar.gz: 9eaf365adb12ab38f7ae908ec3c70e62885e8eda080e302bc5453100b8dca557
 SHA512:
-  metadata.gz: a88a1161a35e016f35a452822edf0c7483b984f9161612b4e433d9782e9177017af7483eab24c03727523dbbb03ba98ad5b25f22683b1e4c5b949aa604f7266e
-  data.tar.gz: 88aeb1e006f5f2e1c2ac9a50d4dfaf4090b36435955ad790aa60b320f17cffe05aa15a998dd630977015e05352e48f54908fbbff0f15316944f6c773546866e2
+  metadata.gz: 17b164ff3752f9b768554bc4959e66323bc523f8cff2de24ee06c3c7274b92f28607f4de1aaf8894e92238b7cba40ebc7cb667405ff1bd4770bc707bac6d79ca
+  data.tar.gz: a7854620322960ccb356aa1dd84943a7e562b65ebd042d4288cfc8b3364004694776301f49a12383ebbd80a0c98c7bdfa8b9de7e4d36295ce03f500edc199336

data/.rubocop.yml

@@ -15,6 +15,15 @@ AllCops:
 Layout/LineLength:
   Max: 120
 
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/MethodLength:
+  Max: 20
+
 Naming/MethodParameterName:
   MinNameLength: 2
 
@@ -27,6 +36,9 @@ RSpec/MultipleExpectations:
 RSpec/NestedGroups:
   Max: 4
 
+RSpec/ExampleLength:
+  Enabled: false
+
 Style/Documentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [2.4.0] - 2025-08-04
+
+- Add Email Templates API
+- Add Contacts API
+- Add Contact Fields API
+- Add Contact Lists API
+- Add Batch Sending
+- Deprecate `Mailtrap::Mail::FromTemplate` in favour of `Mailtrap::Mail.from_template`
+
 ## [2.3.0] - 2025-03-06
 
 - Drop Ruby 3.0 support

data/Gemfile

@@ -5,9 +5,11 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'appraisal'
+gem 'irb'
 gem 'mail'
 gem 'net-smtp'
 gem 'rake', '~> 13.0'
+gem 'rdoc', '~> 6.13.0'
 gem 'rspec', '~> 3.0'
 gem 'rspec-its'
 gem 'rubocop', '~> 1.21'
@@ -15,3 +17,4 @@ gem 'rubocop-rake', require: false
 gem 'rubocop-rspec', require: false
 gem 'vcr'
 gem 'webmock'
+gem 'yard', '~> 0.9'

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    mailtrap (2.3.0)
+    mailtrap (2.4.0)
+      base64
 
 GEM
   remote: https://rubygems.org/
@@ -12,7 +13,8 @@ GEM
       bundler
       rake
       thor (>= 0.14.0)
-    ast (2.4.2)
+    ast (2.4.3)
+    base64 (0.3.0)
     bigdecimal (3.1.8)
     crack (1.0.0)
       bigdecimal
@@ -20,15 +22,21 @@ GEM
     date (3.4.1)
     diff-lcs (1.5.1)
     hashdiff (1.1.0)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
+    io-console (0.8.0)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.12.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
     mail (2.8.1)
       mini_mime (>= 0.1.1)
       net-imap
       net-pop
       net-smtp
     mini_mime (1.1.5)
-    net-imap (0.5.6)
+    net-imap (0.5.7)
       date
       net-protocol
     net-pop (0.1.2)
@@ -37,16 +45,27 @@ GEM
       timeout
     net-smtp (0.5.0)
       net-protocol
-    parallel (1.25.1)
-    parser (3.3.3.0)
+    parallel (1.27.0)
+    parser (3.3.8.0)
       ast (~> 2.4.1)
       racc
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.4.0)
+    psych (5.2.6)
+      date
+      stringio
     public_suffix (5.1.1)
-    racc (1.8.0)
+    racc (1.8.1)
     rainbow (3.1.1)
     rake (13.2.1)
-    regexp_parser (2.9.2)
-    rexml (3.3.9)
+    rdoc (6.13.1)
+      psych (>= 4.0.0)
+    regexp_parser (2.10.0)
+    reline (0.6.1)
+      io-console (~> 0.5)
+    rexml (3.4.1)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -63,42 +82,49 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
-    rubocop (1.64.1)
+    rubocop (1.78.0)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.45.1, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.3)
-      parser (>= 3.3.1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.45.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
     rubocop-rspec (3.0.2)
       rubocop (~> 1.61)
     ruby-progressbar (1.13.0)
+    stringio (3.1.7)
     thor (1.3.1)
     timeout (0.4.3)
-    unicode-display_width (2.5.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
     vcr (6.2.0)
     webmock (3.23.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.37)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   appraisal
+  irb
   mail
   mailtrap!
   net-smtp
   rake (~> 13.0)
+  rdoc (~> 6.13.0)
   rspec (~> 3.0)
   rspec-its
   rubocop (~> 1.21)
@@ -106,6 +132,7 @@ DEPENDENCIES
   rubocop-rspec
   vcr
   webmock
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.6.5

data/README.md

@@ -46,27 +46,89 @@ config.action_mailer.delivery_method = :mailtrap
 ```ruby
 require 'mailtrap'
 
-# create mail object
-mail = Mailtrap::Mail::Base.new(
+# Create mail object
+mail = Mailtrap::Mail.from_content(
   from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
   to: [
     { email: 'your@email.com' }
   ],
   reply_to: { email: 'support@example.com', name: 'Mailtrap Reply-To' },
   subject: 'You are awesome!',
-  text: "Congrats for sending test email with Mailtrap!"
+  text: 'Congrats for sending test email with Mailtrap!'
 )
 
-# create client and send
+# Create client and send
 client = Mailtrap::Client.new(api_key: 'your-api-key')
 client.send(mail)
+
+# You can also pass the request parameters directly
+client.send(
+  from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
+  to: [
+    { email: 'your@email.com' }
+  ],
+  subject: 'You are awesome!',
+  text: 'Congrats for sending test email with Mailtrap!'
+)
+
+```
+
+### Batch Sending
+
+Send up to 500 emails in one API call:
+
+```ruby
+require 'mailtrap'
+
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+
+batch_base = Mailtrap::Mail.batch_base_from_content(
+  from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
+  subject: 'You are awesome!',
+  text: 'Congrats for sending test email with Mailtrap!',
+  html: '<p>Congrats for sending test email with Mailtrap!</p>'
+)
+
+client.send_batch(
+  batch_base, [
+    Mailtrap::Mail.from_content(
+      to: [
+        { email: 'john.doe@email.com', name: 'John Doe' }
+      ]
+    ),
+    Mailtrap::Mail.from_content(
+      to: [
+        { email: 'jane.doe@email.com', name: 'Jane Doe' }
+      ]
+    )
+  ]
+)
+```
+
+### Email Templates API
+
+```ruby
+require 'mailtrap'
+
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+templates = Mailtrap::EmailTemplatesAPI.new 3229, client
+
+templates.create(
+  name: 'Welcome Email',
+  subject: 'Welcome to Mailtrap!',
+  body_html: '<h1>Hello</h1>',
+  body_text: 'Hello',
+  category: 'welcome'
+)
 ```
 
-Refer to the [`examples`](examples) folder for more examples.
+Refer to the [`examples`](examples) folder for more examples:
 
 - [Full](examples/full.rb)
 - [Email template](examples/email_template.rb)
+- [Batch Sending](examples/batch.rb)
 - [ActionMailer](examples/action_mailer.rb)
+- [Email Templates API](examples/email_templates_api.rb)
 
 ### Content-Transfer-Encoding
 
@@ -77,11 +139,35 @@ sending. For example, `/api/send` endpoint ignores `Content-Transfer-Encoding`
 Meaning your recipients will receive emails only in the default encoding which
 is `quoted-printable`, if you send with Mailtrap API.
 
-For those who does need to use `7bit` or any other encoding, SMTP provides
+For those who 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.
 
+### Multiple Mailtrap Clients
+
+You can configure two Mailtrap clients to operate simultaneously. This setup is
+particularly useful when you need to send emails using both the transactional
+and bulk APIs. Refer to the configuration example below:
+
+```ruby
+# config/application.rb
+ActionMailer::Base.add_delivery_method :mailtrap_bulk, Mailtrap::ActionMailer::DeliveryMethod
+
+# config/environments/production.rb
+config.action_mailer.delivery_method = :mailtrap
+config.action_mailer.mailtrap_settings = {
+  api_key: 'your-api-key'
+}
+config.action_mailer.mailtrap_bulk_settings = {
+  api_key: 'your-api-key',
+  bulk: true
+}
+
+# app/mailers/foo_mailer.rb
+mail(delivery_method: :mailtrap_bulk)
+```
+
 ## Migration guide v1 → v2
 
 Change `Mailtrap::Sending::Client` to `Mailtrap::Client`.

data/lib/mailtrap/base_api.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  module BaseAPI
+    attr_reader :account_id, :client
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      attr_accessor :supported_options, :response_class
+    end
+
+    # @param account_id [Integer] The account ID
+    # @param client [Mailtrap::Client] The client instance
+    # @raise [ArgumentError] If account_id is nil
+    def initialize(account_id = ENV.fetch('MAILTRAP_ACCOUNT_ID'), client = Mailtrap::Client.new)
+      raise ArgumentError, 'account_id is required' if account_id.nil?
+
+      @account_id = account_id
+      @client = client
+    end
+
+    private
+
+    def supported_options
+      self.class.supported_options
+    end
+
+    def response_class
+      self.class.response_class
+    end
+
+    def validate_options!(options, supported_options)
+      invalid_options = options.keys - supported_options
+      return if invalid_options.empty?
+
+      raise ArgumentError, "invalid options are given: #{invalid_options}, supported_options: #{supported_options}"
+    end
+
+    def build_entity(options, response_class)
+      response_class.new(options.slice(*response_class.members))
+    end
+
+    def base_get(id)
+      response = client.get("#{base_path}/#{id}")
+      handle_response(response)
+    end
+
+    def base_create(options, supported_options_override = supported_options)
+      validate_options!(options, supported_options_override)
+      response = client.post(base_path, wrap_request(options))
+      handle_response(response)
+    end
+
+    def base_update(id, options, supported_options_override = supported_options)
+      validate_options!(options, supported_options_override)
+      response = client.patch("#{base_path}/#{id}", wrap_request(options))
+      handle_response(response)
+    end
+
+    def base_delete(id)
+      client.delete("#{base_path}/#{id}")
+    end
+
+    def base_list
+      response = client.get(base_path)
+      response.map { |item| handle_response(item) }
+    end
+
+    def handle_response(response)
+      build_entity(response, response_class)
+    end
+
+    def wrap_request(options)
+      options
+    end
+
+    def base_path
+      raise NotImplementedError, 'base_path must be implemented in the including class'
+    end
+  end
+end