Deprecate Mailtrap::Mail::FromTemplate

Gemfile.lock

@@ -13,7 +13,7 @@ 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)
@@ -27,8 +27,9 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
+    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
@@ -44,26 +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)
     rdoc (6.13.1)
       psych (>= 4.0.0)
-    regexp_parser (2.9.2)
+    regexp_parser (2.10.0)
     reline (0.6.1)
       io-console (~> 0.5)
-    rexml (3.3.9)
+    rexml (3.4.1)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -80,19 +82,20 @@ 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)
@@ -101,7 +104,9 @@ GEM
     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)

README.md

@@ -46,20 +46,31 @@ 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: '[email protected]', name: 'Mailtrap Test' },
   to: [
     { email: '[email protected]' }
   ],
   reply_to: { email: '[email protected]', 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: '[email protected]', name: 'Mailtrap Test' },
+  to: [
+    { email: '[email protected]' }
+  ],
+  subject: 'You are awesome!',
+  text: 'Congrats for sending test email with Mailtrap!'
+)
+
 ```
 
 ### Email Templates API

examples/email_template.rb

@@ -1,7 +1,7 @@
 require 'mailtrap'
 
-# create mail object
-mail = Mailtrap::Mail::FromTemplate.new(
+# Create mail object
+mail = Mailtrap::Mail.from_template(
   from: { email: '[email protected]', name: 'Mailtrap Test' },
   to: [
     { email: '[email protected]' }
@@ -13,6 +13,18 @@
   }
 )
 
-# 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: '[email protected]', name: 'Mailtrap Test' },
+  to: [
+    { email: '[email protected]' }
+  ],
+  template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
+  template_variables: {
+    'user_name' => 'John Doe'
+  }
+)

examples/full.rb

@@ -1,7 +1,11 @@
 require 'mailtrap'
 require 'base64'
 
-mail = Mailtrap::Mail::Base.new(
+# You can create a mail object using one of the following:
+# - Mailtrap::Mail.from_content
+# - Mailtrap::Mail.from_template
+# - Mailtrap::Mail::Base.new
+mail = Mailtrap::Mail.from_content(
   from: { email: '[email protected]', name: 'Mailtrap Test' },
   to: [
     { email: '[email protected]', name: 'Your name' }
@@ -52,3 +56,13 @@
 # client = Mailtrap::Client.new(api_key: 'your-api-key', sandbox: true, inbox_id: 12)
 
 client.send(mail)
+
+# You can also pass the request parameters directly
+client.send(
+  from: { email: '[email protected]', name: 'Mailtrap Test' },
+  to: [
+    { email: '[email protected]', name: 'Your name' }
+  ],
+  subject: 'You are awesome!',
+  text: 'Congrats for sending test email with Mailtrap!'
+)

lib/mailtrap/client.rb

@@ -54,14 +54,32 @@ def initialize( # rubocop:disable Metrics/ParameterLists
     end
 
     # Sends an email
-    # @param mail [Mail::Base] The email to send
-    # @return [Hash, nil] The JSON response
+    # @example
+    #   mail = Mailtrap::Mail.from_template(
+    #     from: { email: '[email protected]', name: 'Mailtrap Test' },
+    #     to: [
+    #       { email: '[email protected]' }
+    #     ],
+    #     template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
+    #     template_variables: {
+    #       'user_name' => 'John Doe'
+    #     }
+    #   )
+    #   client.send(mail)
+    # @example
+    #   client.send(
+    #     from: { email: '[email protected]', name: 'Mailtrap Test' },
+    #     to: [
+    #       { email: '[email protected]' }
+    #     ],
+    #     subject: 'You are awesome!',
+    #     text: 'Congrats for sending test email with Mailtrap!'
+    #   )
+    # @param mail [#to_json] The email to send
+    # @return [Hash] The JSON response
     # @!macro api_errors
     # @raise [Mailtrap::MailSizeError] If the message is too large
-    # @raise [ArgumentError] If the mail is not a Mail::Base object
     def send(mail)
-      raise ArgumentError, 'should be Mailtrap::Mail::Base object' unless mail.is_a? Mail::Base
-
       perform_request(:post, api_host, send_path, mail)
     end
 
@@ -118,7 +136,7 @@ def select_api_host(bulk:, sandbox:)
     end
 
     def send_path
-      "/api/send#{sandbox ? "/#{inbox_id}" : ""}"
+      "/api/send#{"/#{inbox_id}" if sandbox}"
     end
 
     def perform_request(method, host, path, body = nil)

lib/mailtrap/mail.rb

@@ -7,8 +7,117 @@
 require_relative 'errors'
 
 module Mailtrap
-  module Mail
+  module Mail # rubocop:disable Metrics/ModuleLength
+    SPECIAL_HEADERS = %w[
+      from
+      to
+      cc
+      bcc
+      subject
+      category
+      customvariables
+      contenttype
+    ].freeze
+    private_constant :SPECIAL_HEADERS
+
+    # ActionMailer adds these headers by calling `Mail::Message#encoded`,
+    # as if the message is to be delivered via SMTP.
+    # Since the message will actually be generated on the Mailtrap side from its components,
+    # the headers are redundant and potentially conflicting, so we remove them.
+    ACTIONMAILER_ADDED_HEADERS = %w[
+      contenttransferencoding
+      date
+      messageid
+      mimeversion
+    ].freeze
+    private_constant :ACTIONMAILER_ADDED_HEADERS
+
+    HEADERS_TO_REMOVE = (SPECIAL_HEADERS + ACTIONMAILER_ADDED_HEADERS).freeze
+    private_constant :HEADERS_TO_REMOVE
+
     class << self
+      # Builds a mail object that will be sent using a pre-defined email
+      # template. The template content (subject, text, html, category) is
+      # defined in the Mailtrap dashboard and referenced by the template_uuid.
+      # Template variables can be passed to customize the template content.
+      # @example
+      #   mail = Mailtrap::Mail.from_template(
+      #     from: { email: '[email protected]', name: 'Mailtrap Test' },
+      #     to: [
+      #       { email: '[email protected]' }
+      #     ],
+      #     template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
+      #     template_variables: {
+      #       'user_name' => 'John Doe'
+      #     }
+      #   )
+      def from_template( # rubocop:disable Metrics/ParameterLists
+        from: nil,
+        to: [],
+        reply_to: nil,
+        cc: [],
+        bcc: [],
+        attachments: [],
+        headers: {},
+        custom_variables: {},
+        template_uuid: nil,
+        template_variables: {}
+      )
+        Mailtrap::Mail::Base.new(
+          from:,
+          to:,
+          reply_to:,
+          cc:,
+          bcc:,
+          attachments:,
+          headers:,
+          custom_variables:,
+          template_uuid:,
+          template_variables:
+        )
+      end
+
+      # Builds a mail object with content including subject, text, html, and category.
+      # @example
+      #   mail = Mailtrap::Mail.from_content(
+      #     from: { email: '[email protected]', name: 'Mailtrap Test' },
+      #     to: [
+      #       { email: '[email protected]' }
+      #     ],
+      #     subject: 'You are awesome!',
+      #     text: 'Congrats for sending test email with Mailtrap!'
+      #   )
+      def from_content( # rubocop:disable Metrics/ParameterLists
+        from: nil,
+        to: [],
+        reply_to: nil,
+        cc: [],
+        bcc: [],
+        attachments: [],
+        headers: {},
+        custom_variables: {},
+        subject: nil,
+        text: nil,
+        html: nil,
+        category: nil
+      )
+        Mailtrap::Mail::Base.new(
+          from:,
+          to:,
+          reply_to:,
+          cc:,
+          bcc:,
+          attachments:,
+          headers:,
+          custom_variables:,
+          subject:,
+          text:,
+          html:,
+          category:
+        )
+      end
+
+      # Builds a mail object from Mail::Message
       # @param message [Mail::Message]
       # @return [Mailtrap::Mail::Base]
       def from_message(message) # rubocop:disable Metrics/AbcSize
@@ -29,30 +138,6 @@ def from_message(message) # rubocop:disable Metrics/AbcSize
 
       private
 
-      SPECIAL_HEADERS = %w[
-        from
-        to
-        cc
-        bcc
-        subject
-        category
-        customvariables
-        contenttype
-      ].freeze
-
-      # ActionMailer adds these headers by calling `Mail::Message#encoded`,
-      # as if the message is to be delivered via SMTP.
-      # Since the message will actually be generated on the Mailtrap side from its components,
-      # the headers are redundant and potentially conflicting, so we remove them.
-      ACTIONMAILER_ADDED_HEADERS = %w[
-        contenttransferencoding
-        date
-        messageid
-        mimeversion
-      ].freeze
-
-      HEADERS_TO_REMOVE = (SPECIAL_HEADERS + ACTIONMAILER_ADDED_HEADERS).freeze
-
       # @param header [Mail::Field, nil]
       # @return [Mail::AddressList, nil]
       def address_list(header)