Deprecate Mailtrap::Mail::FromTemplate

README.md

@@ -46,8 +46,8 @@ 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]' }
@@ -57,9 +57,20 @@ mail = Mailtrap::Mail::Base.new(
   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,11 @@ def initialize( # rubocop:disable Metrics/ParameterLists
     end
 
     # Sends an email
-    # @param mail [Mail::Base] The email to send
-    # @return [Hash, nil] The JSON response
+    # @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
 

lib/mailtrap/mail.rb

@@ -7,8 +7,70 @@
 require_relative 'errors'
 
 module Mailtrap
-  module Mail
+  module Mail # rubocop:disable Metrics/ModuleLength
     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.
+      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.
+      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

lib/mailtrap/mail/base.rb

@@ -5,7 +5,8 @@
 module Mailtrap
   module Mail
     class Base
-      attr_accessor :from, :to, :reply_to, :cc, :bcc, :headers, :custom_variables, :subject, :text, :html, :category
+      attr_accessor :from, :to, :reply_to, :cc, :bcc, :headers, :custom_variables, :subject, :text, :html, :category,
+                    :template_uuid, :template_variables
       attr_reader :attachments
 
       def initialize( # rubocop:disable Metrics/ParameterLists
@@ -20,7 +21,9 @@ def initialize( # rubocop:disable Metrics/ParameterLists
         attachments: [],
         headers: {},
         custom_variables: {},
-        category: nil
+        category: nil,
+        template_uuid: nil,
+        template_variables: {}
       )
         @from = from
         @to = to
@@ -34,6 +37,8 @@ def initialize( # rubocop:disable Metrics/ParameterLists
         @headers = headers
         @custom_variables = custom_variables
         @category = category
+        @template_uuid = template_uuid
+        @template_variables = template_variables
       end
 
       def as_json
@@ -50,8 +55,10 @@ def as_json
           # TODO: update headers and custom_variables with as_json method
           'headers' => headers,
           'custom_variables' => custom_variables,
-          'category' => category
-        }.compact
+          'category' => category,
+          'template_uuid' => template_uuid,
+          'template_variables' => template_variables
+        }.transform_values { |value| presence value }.compact
       end
 
       def to_json(*args)
@@ -77,6 +84,10 @@ def add_attachment(content:, filename:, type: nil, disposition: nil, content_id:
 
         attachment
       end
+
+      def presence(value)
+        value.respond_to?(:empty?) && value.empty? ? nil : value
+      end
     end
   end
 end

lib/mailtrap/mail/from_template.rb

@@ -2,9 +2,8 @@
 
 module Mailtrap
   module Mail
+    # @deprecated Use Mailtrap::Mail::Base
     class FromTemplate < Base
-      attr_accessor :template_uuid, :template_variables
-
       def initialize( # rubocop:disable Metrics/ParameterLists
         from: nil,
         to: [],
@@ -17,27 +16,7 @@ def initialize( # rubocop:disable Metrics/ParameterLists
         template_uuid: nil,
         template_variables: {}
       )
-        super(
-          from:,
-          to:,
-          reply_to:,
-          cc:,
-          bcc:,
-          attachments:,
-          headers:,
-          custom_variables:
-        )
-        @template_uuid = template_uuid
-        @template_variables = template_variables
-      end
-
-      def as_json
-        super.merge(
-          {
-            'template_uuid' => template_uuid,
-            'template_variables' => template_variables
-          }
-        ).compact
+        super
       end
     end
   end