mailtrap 2.9.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1d2ec6f013c1c734b375a56217c2ec6373904851fdc28f25147932bf7d44225
-  data.tar.gz: 3a7c2994b477de66e566ad9cc41c5ca39d70641fa096c92a47af4c0289de6808
+  metadata.gz: b3a95002cbfb65622fa2d944bf2de1d41dc25a9a7224f8d244982fdf8154776d
+  data.tar.gz: a228f3805ce687e8f34bd410595f6e39f9e7d73a426d1d06ca2b35ec972b5c69
 SHA512:
-  metadata.gz: 1c2176601df89656a773772072952169caf35c0cff0d193cdab25c07956d09d9ab828b9e2995581512312f8e33f35605623b89052950752d8fc6a6c13cb3f0fc
-  data.tar.gz: 7661abf25236f9bec0a26f5463d92074a2e76b18bb9f5fc1067c3b2f810a7eed518e1a0d211ac61c11cde4eaaeb4542376ddd5ebd9785678adb225be3838092b
+  metadata.gz: fcec8536fae46762bd7289b7b098f45728c9d00b79bcd1386b6e4cb384fa0fcf859136db5cc956480da7aa1cb5063ed8dbee2312ac0e2bf6c8ac4b872443e650
+  data.tar.gz: 127126f80cded1f05214a173b1c8e78b8acc6c39bdbf1f168b161ca221a5e4230aa11d098f26c8c188c14778a28c579ac0e2bea52bab2713c82068d43836b677

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [2.10.0] - 2026-03-23
+
+- Add Email Logs API (list and get email sending logs with filters and cursor pagination)
+- Add `list_each` to Sandbox Messages API for automatic pagination over all messages
+
 ## [2.9.0] - 2026-03-13
 
 - Add Sending Stats API

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mailtrap (2.9.0)
+    mailtrap (2.10.0)
       base64
 
 GEM

data/README.md

@@ -178,6 +178,7 @@ Email API:
 - Batch Sending – [`batch.rb`](examples/batch.rb)
 - Sending Domains API  – [`sending_domains_api.rb`](examples/sending_domains_api.rb)
 - Sending Stats API – [`stats_api.rb`](examples/stats_api.rb)
+- Email Logs API – [`email_logs_api.rb`](examples/email_logs_api.rb)
 
 Email Sandbox (Testing):
 

data/lib/mailtrap/email_log_event.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an email log event (delivery, open, click, bounce, etc.)
+  # @see https://docs.mailtrap.io/developers/email-sending/email-logs
+  # @attr_reader event_type [String] One of: delivery, open, click, soft_bounce, bounce, spam, unsubscribe, suspension,
+  #   reject
+  # @attr_reader created_at [String] ISO 8601 timestamp
+  # @attr_reader details [EmailLogEventDetails::Delivery, EmailLogEventDetails::Open, EmailLogEventDetails::Click,
+  #   EmailLogEventDetails::Bounce, EmailLogEventDetails::Spam, EmailLogEventDetails::Unsubscribe,
+  #   EmailLogEventDetails::Reject] Type-specific event details
+  EmailLogEvent = Struct.new(
+    :event_type,
+    :created_at,
+    :details,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/email_log_event_details.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Type-specific event detail structs for EmailLogEvent. Use event_type to determine which details schema applies.
+  # @see https://docs.mailtrap.io/developers/email-sending/email-logs
+  module EmailLogEventDetails
+    # For event_type = delivery
+    Delivery = Struct.new(:sending_ip, :recipient_mx, :email_service_provider, keyword_init: true)
+
+    # For event_type = open
+    Open = Struct.new(:web_ip_address, keyword_init: true)
+
+    # For event_type = click
+    Click = Struct.new(:click_url, :web_ip_address, keyword_init: true)
+
+    # For event_type = soft_bounce or bounce
+    Bounce = Struct.new(
+      :sending_ip,
+      :recipient_mx,
+      :email_service_provider,
+      :email_service_provider_status,
+      :email_service_provider_response,
+      :bounce_category,
+      keyword_init: true
+    )
+
+    # For event_type = spam
+    Spam = Struct.new(:spam_feedback_type, keyword_init: true)
+
+    # For event_type = unsubscribe
+    Unsubscribe = Struct.new(:web_ip_address, keyword_init: true)
+
+    # For event_type = suspension or reject
+    Reject = Struct.new(:reject_reason, keyword_init: true)
+
+    DETAIL_STRUCTS = {
+      'delivery' => Delivery,
+      'open' => Open,
+      'click' => Click,
+      'soft_bounce' => Bounce,
+      'bounce' => Bounce,
+      'spam' => Spam,
+      'unsubscribe' => Unsubscribe,
+      'suspension' => Reject,
+      'reject' => Reject
+    }.freeze
+
+    # Builds the appropriate detail struct from API response.
+    # @param event_type [String] Known event type (delivery, open, click, etc.)
+    # @param hash [Hash] Symbol-keyed details from parsed JSON
+    # @return [Delivery, Open, Click, Bounce, Spam, Unsubscribe, Reject]
+    # @raise [ArgumentError] when event_type is nil or not in DETAIL_STRUCTS
+    def self.build(event_type, hash)
+      struct_class = DETAIL_STRUCTS[event_type.to_s]
+      raise ArgumentError, "Unknown event_type: #{event_type.inspect}" unless struct_class
+
+      attrs = hash.slice(*struct_class.members)
+      struct_class.new(**attrs)
+    end
+  end
+end

data/lib/mailtrap/email_log_message.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an email log message (summary in list, full details when fetched by ID)
+  # @see https://docs.mailtrap.io/developers/email-sending/email-logs
+  # @attr_reader message_id [String] Message UUID
+  # @attr_reader status [String] delivered, not_delivered, enqueued, opted_out
+  # @attr_reader subject [String, nil] Email subject
+  # @attr_reader from [String] Sender address
+  # @attr_reader to [String] Recipient address
+  # @attr_reader sent_at [String] ISO 8601 timestamp
+  # @attr_reader client_ip [String, nil] Client IP that sent the email
+  # @attr_reader category [String, nil] Message category
+  # @attr_reader custom_variables [Hash, nil] Custom variables
+  # @attr_reader sending_stream [String] transactional or bulk
+  # @attr_reader sending_domain_id [Integer] Sending domain ID
+  # @attr_reader template_id [Integer, nil] Template ID if sent from template
+  # @attr_reader template_variables [Hash, nil] Template variables
+  # @attr_reader opens_count [Integer] Number of opens
+  # @attr_reader clicks_count [Integer] Number of clicks
+  # @attr_reader raw_message_url [String, nil] Signed URL to download raw .eml (only when fetched by ID)
+  # @attr_reader events [Array<EmailLogEvent>, nil] Event list (only when fetched by ID)
+  EmailLogMessage = Struct.new(
+    :message_id,
+    :status,
+    :subject,
+    :from,
+    :to,
+    :sent_at,
+    :client_ip,
+    :category,
+    :custom_variables,
+    :sending_stream,
+    :sending_domain_id,
+    :template_id,
+    :template_variables,
+    :opens_count,
+    :clicks_count,
+    :raw_message_url,
+    :events,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/email_logs_api.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'email_log_message'
+require_relative 'email_log_event'
+require_relative 'email_log_event_details'
+require_relative 'email_logs_list_response'
+
+module Mailtrap
+  class EmailLogsAPI
+    include BaseAPI
+
+    self.response_class = EmailLogMessage
+
+    # Lists email logs with optional filters and cursor-based pagination.
+    #
+    # @param filters [Hash, nil] Optional filters. Top-level date keys use string values (ISO 8601);
+    #   other keys use +{ operator:, value: }+. +value+ can be a single value or an Array for
+    #   operators that accept multiple values (e.g. +equal+, +not_equal+, +ci_equal+, +ci_not_equal+).
+    #   Examples:
+    #   +{ sent_after: "2025-01-01T00:00:00Z", sent_before: "2025-01-31T23:59:59Z" }+
+    #   +{ to: { operator: "ci_equal", value: "recipient@example.com" } }+
+    #   +{ category: { operator: "equal", value: ["Welcome Email", "Transactional Email"] } }+
+    # @param search_after [String, nil] Message UUID cursor for the next page (from previous +next_page_cursor+)
+    # @return [EmailLogsListResponse] messages, total_count, and next_page_cursor
+    # @!macro api_errors
+    def list(filters: nil, search_after: nil)
+      query_params = build_list_query_params(filters:, search_after:)
+
+      response = client.get(base_path, query_params)
+
+      build_list_response(response)
+    end
+
+    # Iterates over all email log messages matching the filters, automatically fetching each page.
+    # Use this when you want to process every message without manually handling +next_page_cursor+.
+    #
+    # @param filters [Hash, nil] Same as +list+
+    # @yield [EmailLogMessage] Gives each message from every page when a block is given.
+    # @return [Enumerator<EmailLogMessage>] if no block given; otherwise the result of the block
+    # @!macro api_errors
+    def list_each(filters: nil, &block)
+      first_page = nil
+      fetch_first_page = -> { first_page ||= list(filters: filters) }
+      enum = Enumerator.new(-> { fetch_first_page.call.total_count }) do |yielder|
+        response = fetch_first_page.call
+        loop do
+          response.messages.each { |message| yielder << message }
+          break if response.next_page_cursor.nil?
+
+          response = list(filters: filters, search_after: response.next_page_cursor)
+        end
+      end
+
+      block ? enum.each(&block) : enum
+    end
+
+    # Fetches a single email log message by ID.
+    #
+    # @param sending_message_id [String] Message UUID
+    # @return [EmailLogMessage] Message with events and raw_message_url when available
+    # @!macro api_errors
+    def get(sending_message_id)
+      base_get(sending_message_id)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/email_logs"
+    end
+
+    def build_list_query_params(filters:, search_after:)
+      {}.tap do |params|
+        params[:search_after] = search_after if search_after
+        params.merge!(flatten_filters(filters))
+      end
+    end
+
+    # Flattens a filters Hash into query param keys expected by the API (deepObject style).
+    # Scalar values => filters[key]; Hashes with :operator/:value => filters[key][operator], filters[key][value].
+    # When :value is an Array, the key is repeated (e.g. filters[category][value]=A&filters[category][value]=B)
+    # for operators that accept multiple values (e.g. equal, not_equal, ci_equal, ci_not_equal).
+    def flatten_filters(filters)
+      return {} if filters.nil? || filters.empty?
+
+      filters.each_with_object({}) do |(key, value), result|
+        if value.is_a?(Hash)
+          flatten_filter_hash(key, value, result)
+        else
+          result["filters[#{key}]"] = value.to_s
+        end
+      end
+    end
+
+    def flatten_filter_hash(parent_key, hash, result)
+      hash.each do |key, value|
+        if value.is_a?(Array)
+          result["filters[#{parent_key}][#{key}][]"] = value.map(&:to_s)
+        else
+          result["filters[#{parent_key}][#{key}]"] = value.to_s
+        end
+      end
+    end
+
+    def build_list_response(response)
+      EmailLogsListResponse.new(
+        messages: Array(response[:messages]).map { |item| handle_response(item) },
+        total_count: response[:total_count],
+        next_page_cursor: response[:next_page_cursor]
+      )
+    end
+
+    def handle_response(response)
+      build_message_entity(response)
+    end
+
+    def build_message_entity(hash)
+      attrs = hash.slice(*EmailLogMessage.members)
+      attrs[:events] = build_events(attrs[:events]) if attrs[:events]
+
+      EmailLogMessage.new(**attrs)
+    end
+
+    def build_events(events_array)
+      Array(events_array).map do |e|
+        EmailLogEvent.new(
+          event_type: e[:event_type],
+          created_at: e[:created_at],
+          details: EmailLogEventDetails.build(e[:event_type], e[:details])
+        )
+      end
+    end
+  end
+end

data/lib/mailtrap/email_logs_list_response.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Response from listing email logs (paginated)
+  # @see https://docs.mailtrap.io/developers/email-sending/email-logs
+  # @attr_reader messages [Array<EmailLogMessage>] Page of message summaries
+  # @attr_reader total_count [Integer] Total number of messages matching filters
+  # @attr_reader next_page_cursor [String, nil] Message UUID to use as search_after for next page, or nil
+  EmailLogsListResponse = Struct.new(
+    :messages,
+    :total_count,
+    :next_page_cursor,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/sandbox_messages_api.rb

@@ -51,6 +51,26 @@ module Mailtrap
       base_update(message_id, { is_read: is_read })
     end
 
+    # Iterates over all sandbox messages, automatically fetching each page
+    # using cursor-based pagination. Use this when you want to process messages
+    # without manually handling pagination.
+    # @param search [String] Search query string. Matches subject, to_email, and to_name.
+    # @yield [SandboxMessage] Gives each message from every page when a block is given.
+    # @return [Enumerator<SandboxMessage>] if no block given; otherwise the result of the block
+    # @!macro api_errors
+    def list_each(search: nil, &block)
+      return to_enum(__method__, search: search) unless block
+
+      last_id = nil
+      loop do
+        messages = list(search: search, last_id: last_id)
+        break if messages.empty?
+
+        messages.each { |message| block.call(message) }
+        last_id = messages.last.id
+      end
+    end
+
     # Lists all sandbox messages for the account, limited up to 30 at once
     # @param search [String] Search query string. Matches subject, to_email, and to_name.
     # @param last_id [Integer] If specified, a page of records before last_id is returned.

data/lib/mailtrap/version.rb

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

data/lib/mailtrap.rb

@@ -14,6 +14,7 @@ require_relative 'mailtrap/contact_fields_api'
 require_relative 'mailtrap/contact_imports_api'
 require_relative 'mailtrap/suppressions_api'
 require_relative 'mailtrap/sending_domains_api'
+require_relative 'mailtrap/email_logs_api'
 require_relative 'mailtrap/projects_api'
 require_relative 'mailtrap/inboxes_api'
 require_relative 'mailtrap/sandbox_messages_api'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.9.0
+  version: 2.10.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
@@ -63,6 +63,11 @@ files:
 - lib/mailtrap/contact_lists_api.rb
 - lib/mailtrap/contacts_api.rb
 - lib/mailtrap/contacts_import_request.rb
+- lib/mailtrap/email_log_event.rb
+- lib/mailtrap/email_log_event_details.rb
+- lib/mailtrap/email_log_message.rb
+- lib/mailtrap/email_logs_api.rb
+- lib/mailtrap/email_logs_list_response.rb
 - lib/mailtrap/email_template.rb
 - lib/mailtrap/email_templates_api.rb
 - lib/mailtrap/errors.rb