Add support for Email Logs API

CHANGELOG.md

@@ -1,3 +1,7 @@
+## [Unreleased]
+
+- Add Email Logs API (list and get email sending logs with filters and cursor pagination)
+
 ## [2.9.0] - 2026-03-13
 
 - Add Sending Stats API

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):
 

examples/email_logs_api.rb

@@ -0,0 +1,54 @@
+require 'time'
+require 'mailtrap'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+email_logs = Mailtrap::EmailLogsAPI.new(account_id, client)
+
+# Set your API credentials as environment variables
+# export MAILTRAP_API_KEY='your-api-key'
+# export MAILTRAP_ACCOUNT_ID=your-account-id
+#
+# email_logs = Mailtrap::EmailLogsAPI.new
+
+# List email logs (first page)
+response = email_logs.list
+# => #<struct Mailtrap::EmailLogsListResponse
+#      messages=[#<struct Mailtrap::EmailLogMessage message_id="...", status="delivered", ...>, ...],
+#      total_count=150,
+#      next_page_cursor="b2c3d4e5-f6a7-8901-bcde-f12345678901">
+
+response.messages.each { |m| puts "#{m.message_id} #{m.status} #{m.subject}" }
+
+# List with filters (date range: last 2 days, recipient, status)
+sent_after = (Time.now.utc - (2 * 24 * 3600)).iso8601
+sent_before = Time.now.utc.iso8601
+filters = {
+  sent_after: sent_after,
+  sent_before: sent_before,
+  subject: { operator: 'not_empty' },
+  to: { operator: 'ci_equal', value: 'recipient@example.com' },
+  category: { operator: 'equal', value: %w[Newsletter Alert] }
+}
+response = email_logs.list(filters: filters)
+
+# List next page using cursor from previous response (keep same filters)
+response = email_logs.list(filters: filters, search_after: response.next_page_cursor) if response.next_page_cursor
+
+# Alternative: iterate all pages with list_each (no manual cursor handling)
+email_logs.list_each(filters: filters) { |m| puts "#{m.message_id} #{m.status} #{m.subject}" }
+# Or as enumerator:
+email_logs.list_each(filters: filters).each { |m| puts m.message_id }
+
+# Get a single message by ID (includes events and raw_message_url)
+message_id = response.messages.first&.message_id
+if message_id
+  message = email_logs.get(message_id)
+  # => #<struct Mailtrap::EmailLogMessage
+  #      message_id="a1b2c3d4-...", status="delivered", subject="Welcome", ...,
+  #      raw_message_url="https://storage.../signed/eml/...",
+  #      events=[#<struct Mailtrap::EmailLogEvent event_type="delivery", ...>, ...]>
+
+  puts message.raw_message_url
+  message.events&.each { |e| puts "#{e.event_type} at #{e.created_at}" }
+end

lib/mailtrap.rb

@@ -14,6 +14,7 @@
 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'

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

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

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

lib/mailtrap/email_logs_api.rb

@@ -0,0 +1,132 @@
+# 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)
+      return to_enum(__method__, filters: filters) unless block
+
+      search_after = nil
+      loop do
+        response = list(filters: filters, search_after: search_after)
+        response.messages.each { |message| block.call(message) }
+        break if response.next_page_cursor.nil?
+
+        search_after = response.next_page_cursor
+      end
+    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

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