mailtrap 2.3.0 → 2.4.0

data/lib/mailtrap/email_templates_api.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'email_template'
+
+module Mailtrap
+  class EmailTemplatesAPI
+    include BaseAPI
+
+    self.supported_options = %i[name subject category body_html body_text]
+
+    self.response_class = EmailTemplate
+
+    # Lists all email templates for the account
+    # @return [Array<EmailTemplate>] Array of template objects
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    # Retrieves a specific email template
+    # @param template_id [Integer] The template ID
+    # @return [EmailTemplate] Template object
+    # @!macro api_errors
+    def get(template_id)
+      base_get(template_id)
+    end
+
+    # Creates a new email template
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The template name
+    # @option options [String] :subject The email subject
+    # @option options [String] :category The template category
+    # @option options [String, nil] :body_html The HTML content. Default: nil.
+    # @option options [String, nil] :body_text The plain text content. Default: nil.
+    # @return [EmailTemplate] Created template object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing email template
+    # @param template_id [Integer] The template ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The template name
+    # @option options [String] :subject The email subject
+    # @option options [String] :category The template category
+    # @option options [String, nil] :body_html The HTML content
+    # @option options [String, nil] :body_text The plain text content
+    # @return [EmailTemplate] Updated template object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(template_id, options)
+      base_update(template_id, options)
+    end
+
+    # Deletes an email template
+    # @param template_id [Integer] The template ID
+    # @return nil
+    # @!macro api_errors
+    def delete(template_id)
+      base_delete(template_id)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/email_templates"
+    end
+
+    def wrap_request(options)
+      { email_template: options }
+    end
+  end
+end

data/lib/mailtrap/mail/base.rb

@@ -5,10 +5,11 @@ require 'json'
 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, Metrics/MethodLength
+      def initialize( # rubocop:disable Metrics/ParameterLists
         from: nil,
         to: [],
         reply_to: nil,
@@ -20,7 +21,9 @@ module Mailtrap
         attachments: [],
         headers: {},
         custom_variables: {},
-        category: nil
+        category: nil,
+        template_uuid: nil,
+        template_variables: {}
       )
         @from = from
         @to = to
@@ -34,9 +37,11 @@ module Mailtrap
         @headers = headers
         @custom_variables = custom_variables
         @category = category
+        @template_uuid = template_uuid
+        @template_variables = template_variables
       end
 
-      def as_json # rubocop:disable Metrics/MethodLength
+      def as_json
         {
           'from' => from,
           'to' => to,
@@ -50,8 +55,10 @@ module Mailtrap
           # 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 @@ module Mailtrap
 
         attachment
       end
+
+      def presence(value)
+        value.respond_to?(:empty?) && value.empty? ? nil : value
+      end
     end
   end
 end

data/lib/mailtrap/mail/from_template.rb

@@ -2,10 +2,9 @@
 
 module Mailtrap
   module Mail
+    # @deprecated Use Mailtrap::Mail::Base
     class FromTemplate < Base
-      attr_accessor :template_uuid, :template_variables
-
-      def initialize( # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+      def initialize( # rubocop:disable Metrics/ParameterLists
         from: nil,
         to: [],
         reply_to: nil,
@@ -17,27 +16,7 @@ module Mailtrap
         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

data/lib/mailtrap/mail.rb

@@ -7,11 +7,189 @@ require_relative 'mail/from_template'
 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: 'mailtrap@example.com', name: 'Mailtrap Test' },
+      #     to: [
+      #       { email: 'your@email.com' }
+      #     ],
+      #     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: 'mailtrap@example.com', name: 'Mailtrap Test' },
+      #     to: [
+      #       { email: 'your@email.com' }
+      #     ],
+      #     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 base mail object for batch sending using a pre-defined email template.
+      # This "base" defines shared properties (such as sender, reply-to, template UUID, and template variables)
+      # that will be used as defaults for all emails in the batch. Individual batch requests can override these values.
+      # Use this method when you want to send multiple emails with similar content, leveraging a template defined in the Mailtrap dashboard. # rubocop:disable Layout/LineLength
+      # Template variables can be passed to customize the template content for all recipients, and can be overridden per request. # rubocop:disable Layout/LineLength
+      # @example
+      #   base_mail = Mailtrap::Mail.batch_base_from_template(
+      #     from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
+      #     template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
+      #     template_variables: {
+      #       'user_name' => 'John Doe'
+      #     }
+      #   )
+      #   # Use base_mail as the base for batch sending with Mailtrap::Client#send_batch
+      def batch_base_from_template( # rubocop:disable Metrics/ParameterLists
+        from: nil,
+        reply_to: nil,
+        attachments: [],
+        headers: {},
+        custom_variables: {},
+        template_uuid: nil,
+        template_variables: {}
+      )
+        Mailtrap::Mail::Base.new(
+          from:,
+          reply_to:,
+          attachments:,
+          headers:,
+          custom_variables:,
+          template_uuid:,
+          template_variables:
+        )
+      end
+
+      # Builds a base mail object for batch sending with custom content (subject, text, html, category).
+      # This "base" defines shared properties for all emails in the batch, such as sender, subject, and body.
+      # Individual batch requests can override these values as needed.
+      # Use this method when you want to send multiple emails with similar custom content to different recipients.
+      # @example
+      #   base_mail = Mailtrap::Mail.batch_base_from_content(
+      #     from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
+      #     subject: 'You are awesome!',
+      #     text: 'Congrats for sending test email with Mailtrap!'
+      #   )
+      #   # Use base_mail as the base for batch sending with Mailtrap::Client#send_batch
+      def batch_base_from_content( # rubocop:disable Metrics/ParameterLists
+        from: nil,
+        reply_to: nil,
+        attachments: [],
+        headers: {},
+        custom_variables: {},
+        subject: nil,
+        text: nil,
+        html: nil,
+        category: nil
+      )
+        Mailtrap::Mail::Base.new(
+          from:,
+          reply_to:,
+          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, Metrics/MethodLength
+      def from_message(message) # rubocop:disable Metrics/AbcSize
         Mailtrap::Mail::Base.new(
           from: prepare_addresses(address_list(message['from'])&.addresses).first,
           to: prepare_addresses(address_list(message['to'])&.addresses),
@@ -29,30 +207,6 @@ module Mailtrap
 
       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)

data/lib/mailtrap/version.rb

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

data/lib/mailtrap.rb

@@ -4,5 +4,15 @@ require_relative 'mailtrap/action_mailer' if defined? ActionMailer
 require_relative 'mailtrap/mail'
 require_relative 'mailtrap/errors'
 require_relative 'mailtrap/version'
+require_relative 'mailtrap/email_templates_api'
+require_relative 'mailtrap/contacts_api'
+require_relative 'mailtrap/contact_lists_api'
+require_relative 'mailtrap/contact_fields_api'
 
-module Mailtrap; end
+module Mailtrap
+  # @!macro api_errors
+  #   @raise [Mailtrap::Error] If the API request fails with a client or server error
+  #   @raise [Mailtrap::AuthorizationError] If the API key is invalid
+  #   @raise [Mailtrap::RejectionError] If the server refuses to process the request
+  #   @raise [Mailtrap::RateLimitError] If too many requests are made
+end

data/mailtrap.gemspec

@@ -19,6 +19,8 @@ Gem::Specification.new do |spec|
   spec.metadata['changelog_uri'] = 'https://github.com/railsware/mailtrap-ruby/blob/main/CHANGELOG.md'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
+  spec.add_dependency 'base64'
+
   # Specify which files should be added to the gem when it is released.
   # 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

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-07 00:00:00.000000000 Z
-dependencies: []
+date: 2025-08-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Official mailtrap.io API client
 email:
 - support@mailtrap.io
@@ -32,7 +46,16 @@ files:
 - lib/mailtrap/action_mailer/delivery_method.rb
 - lib/mailtrap/action_mailer/railtie.rb
 - lib/mailtrap/attachment.rb
+- lib/mailtrap/base_api.rb
 - lib/mailtrap/client.rb
+- lib/mailtrap/contact.rb
+- lib/mailtrap/contact_field.rb
+- lib/mailtrap/contact_fields_api.rb
+- lib/mailtrap/contact_list.rb
+- lib/mailtrap/contact_lists_api.rb
+- lib/mailtrap/contacts_api.rb
+- lib/mailtrap/email_template.rb
+- lib/mailtrap/email_templates_api.rb
 - lib/mailtrap/errors.rb
 - lib/mailtrap/mail.rb
 - lib/mailtrap/mail/base.rb