mailer-log 0.1.0

data/app/controllers/mailer_log/webhooks_controller.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module MailerLog
+  class WebhooksController < ActionController::Base
+    skip_before_action :verify_authenticity_token
+
+    before_action :verify_signature
+    before_action :deduplicate_event
+
+    # POST /mailer_log/webhooks/mailgun
+    def mailgun
+      event_data = params['event-data'] || params
+
+      email = find_email(event_data)
+      unless email
+        Rails.logger.info("MailerLog: Email not found for webhook event")
+        return head :ok
+      end
+
+      normalized_event = normalize_event_type(event_data['event'])
+      create_event(email, event_data, normalized_event)
+      email.update_status_from_event!(normalized_event)
+
+      head :ok
+    rescue StandardError => e
+      Rails.logger.error("MailerLog webhook error: #{e.message}")
+      Rails.logger.error(e.backtrace.first(5).join("\n"))
+      report_error(e)
+      head :ok # Return 200 to prevent Mailgun retries for processing errors
+    end
+
+    private
+
+    def verify_signature
+      signature = params['signature']
+      return head :unauthorized unless signature
+
+      timestamp = signature['timestamp']
+      token = signature['token']
+      sig = signature['signature']
+
+      return head :unauthorized unless timestamp && token && sig
+
+      signing_key = MailerLog.configuration.webhook_signing_key
+      return head :unauthorized unless signing_key
+
+      expected = OpenSSL::HMAC.hexdigest(
+        OpenSSL::Digest.new('SHA256'),
+        signing_key,
+        "#{timestamp}#{token}"
+      )
+
+      return if ActiveSupport::SecurityUtils.secure_compare(expected, sig)
+
+      head :unauthorized
+    end
+
+    def deduplicate_event
+      event_id = params.dig('event-data', 'id')
+      return true unless event_id
+
+      cache_key = "mailer_log:event:#{event_id}"
+
+      if Rails.cache.exist?(cache_key)
+        head :ok
+        return false
+      end
+
+      Rails.cache.write(cache_key, true, expires_in: 24.hours)
+      true
+    end
+
+    def find_email(event_data)
+      # Try message_id first
+      message_id = event_data.dig('message', 'headers', 'message-id')
+      if message_id.present?
+        email = Email.find_by(message_id: message_id.gsub(/[<>]/, ''))
+        return email if email
+      end
+
+      # Fallback to tracking_id from custom header
+      tracking_id = event_data.dig('message', 'headers', 'x-mailer-log-tracking-id')
+      Email.find_by(tracking_id: tracking_id) if tracking_id.present?
+    end
+
+    def create_event(email, event_data, normalized_event)
+      email.events.create!(
+        event_type: normalized_event,
+        mailgun_event_id: event_data['id'],
+        occurred_at: extract_timestamp(event_data),
+        recipient: event_data['recipient'],
+        ip_address: event_data['ip'],
+        user_agent: event_data.dig('client-info', 'user-agent'),
+        raw_payload: event_data.to_unsafe_h
+      )
+    end
+
+    def normalize_event_type(mailgun_event)
+      case mailgun_event
+      when 'permanent_fail' then 'bounced'
+      when 'temporary_fail' then 'failed'
+      else mailgun_event
+      end
+    end
+
+    def extract_timestamp(event_data)
+      timestamp = event_data['timestamp']
+      Time.zone.at(timestamp.to_f) if timestamp.present?
+    end
+
+    def report_error(exception)
+      Airbrake.notify(exception) if defined?(Airbrake)
+    end
+  end
+end

data/app/helpers/mailer_log/spa_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module MailerLog
+  module SpaHelper
+    def mailer_log_asset_path(name)
+      manifest = mailer_log_manifest
+      return "/admin/email_log/assets/#{name}" unless manifest
+
+      entry = manifest[name] || manifest["src/#{name}"] || manifest["assets/#{name}"]
+      return "/admin/email_log/assets/#{name}" unless entry
+
+      file = entry.is_a?(Hash) ? entry['file'] : entry
+      "/admin/email_log/assets/#{file}"
+    end
+
+    def mailer_log_js_entry
+      manifest = mailer_log_manifest
+      return nil unless manifest
+
+      entry = manifest['index.html'] || manifest['src/main.js']
+      return nil unless entry
+
+      entry.is_a?(Hash) ? entry['file'] : entry
+    end
+
+    def mailer_log_css_entry
+      manifest = mailer_log_manifest
+      return nil unless manifest
+
+      entry = manifest['index.html']
+      return nil unless entry.is_a?(Hash)
+
+      css_files = entry['css']
+      css_files&.first
+    end
+
+    private
+
+    def mailer_log_manifest
+      @mailer_log_manifest ||= begin
+        manifest_path = MailerLog::Engine.root.join('public', 'mailer_log', '.vite', 'manifest.json')
+        return nil unless File.exist?(manifest_path)
+
+        JSON.parse(File.read(manifest_path))
+      end
+    end
+  end
+end

data/app/jobs/mailer_log/application_job.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module MailerLog
+  class ApplicationJob < ActiveJob::Base
+    # Retry on common transient failures
+    retry_on ActiveRecord::Deadlocked, wait: 5.seconds, attempts: 3
+    retry_on ActiveRecord::LockWaitTimeout, wait: 5.seconds, attempts: 3
+
+    # Discard job on unrecoverable errors
+    discard_on ActiveJob::DeserializationError
+  end
+end

data/app/jobs/mailer_log/cleanup_job.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MailerLog
+  class CleanupJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      retention_period = MailerLog.configuration.retention_period
+      cutoff_date = retention_period.ago
+
+      deleted_count = MailerLog::Email.where('created_at < ?', cutoff_date).delete_all
+
+      Rails.logger.info("MailerLog::CleanupJob: Deleted #{deleted_count} emails older than #{cutoff_date}")
+    end
+  end
+end

data/app/models/mailer_log/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MailerLog
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/mailer_log/current.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MailerLog
+  # Thread-safe storage for passing data between interceptor and observer.
+  # Uses ActiveSupport::CurrentAttributes which automatically resets
+  # between requests and is safe for multi-threaded servers.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :email_data
+  end
+end

data/app/models/mailer_log/email.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module MailerLog
+  class Email < ApplicationRecord
+    self.table_name = 'mailer_log_emails'
+
+    STATUSES = %w[pending sent delivered opened clicked bounced complained].freeze
+
+    has_many :events, class_name: 'MailerLog::Event', dependent: :delete_all
+
+    belongs_to :accountable, polymorphic: true, optional: true
+
+    validates :tracking_id, presence: true, uniqueness: true
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :by_status, ->(status) { where(status: status) }
+    scope :by_mailer, ->(mailer_class) { where(mailer_class: mailer_class) }
+    scope :recent, -> { order(created_at: :desc) }
+
+    # Scopes for filtering
+    scope :recipient, ->(email) { where('? = ANY(to_addresses)', email) }
+    scope :sender, ->(val) { where('from_address ILIKE ?', "%#{val}%") }
+    scope :subject_search, ->(val) { where('subject ILIKE ?', "%#{val}%") }
+    scope :mailer, ->(val) { where(mailer_class: val) }
+    scope :date_from, ->(date) { where('created_at >= ?', date.to_date.beginning_of_day) }
+    scope :date_to, ->(date) { where('created_at <= ?', date.to_date.end_of_day) }
+
+    def update_status_from_event!(event_type)
+      case event_type
+      when 'delivered'
+        update!(status: 'delivered', delivered_at: Time.current) unless opened_at? || clicked_at?
+      when 'opened'
+        update!(status: 'opened', opened_at: Time.current) unless clicked_at?
+      when 'clicked'
+        update!(status: 'clicked', clicked_at: Time.current)
+      when 'bounced', 'failed', 'dropped'
+        update!(status: 'bounced', bounced_at: Time.current)
+      when 'complained'
+        update!(status: 'complained')
+      end
+    end
+
+    def recipients
+      (to_addresses + cc_addresses + bcc_addresses).compact.uniq
+    end
+  end
+end

data/app/models/mailer_log/event.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MailerLog
+  class Event < ApplicationRecord
+    self.table_name = 'mailer_log_events'
+
+    EVENT_TYPES = %w[
+      accepted
+      delivered
+      opened
+      clicked
+      bounced
+      failed
+      dropped
+      complained
+      unsubscribed
+    ].freeze
+
+    belongs_to :email, class_name: 'MailerLog::Email', inverse_of: :events
+
+    validates :event_type, presence: true, inclusion: { in: EVENT_TYPES }
+    validates :mailgun_event_id, uniqueness: true, allow_nil: true
+
+    scope :by_type, ->(type) { where(event_type: type) }
+    scope :recent, -> { order(occurred_at: :desc) }
+  end
+end

data/app/views/mailer_log/admin/emails/_email.html.erb

@@ -0,0 +1,29 @@
+<tr>
+  <td class="text-nowrap">
+    <%= email.created_at.strftime('%Y-%m-%d %H:%M') %>
+  </td>
+  <td>
+    <small class="text-muted"><%= email.mailer_class %></small><br>
+    <code class="small"><%= email.mailer_action %></code>
+  </td>
+  <td class="text-truncate" style="max-width: 200px;">
+    <%= email.to_addresses.join(', ') %>
+  </td>
+  <td class="text-truncate" style="max-width: 250px;">
+    <%= link_to email.subject.presence || '(no subject)', mailer_log_engine.admin_email_path(email) %>
+  </td>
+  <td>
+    <% status_class = case email.status
+       when 'delivered', 'opened', 'clicked' then 'success'
+       when 'bounced', 'complained' then 'danger'
+       when 'sent' then 'info'
+       else 'secondary'
+       end %>
+    <span class="badge badge-<%= status_class %>"><%= email.status %></span>
+  </td>
+  <td class="text-right">
+    <%= link_to mailer_log_engine.admin_email_path(email), class: 'btn btn-sm btn-outline-primary' do %>
+      <i class="far fa-eye"></i>
+    <% end %>
+  </td>
+</tr>

data/app/views/mailer_log/admin/emails/_filters.html.erb

@@ -0,0 +1,58 @@
+<%= form_tag mailer_log_engine.admin_emails_path, method: :get, class: 'mb-3' do %>
+  <div class="row">
+    <div class="col-md-2">
+      <div class="form-group">
+        <label class="small text-muted">Recipient</label>
+        <%= text_field_tag :recipient, params[:recipient], class: 'form-control form-control-sm', placeholder: 'Email address' %>
+      </div>
+    </div>
+    <div class="col-md-2">
+      <div class="form-group">
+        <label class="small text-muted">Sender</label>
+        <%= text_field_tag :sender, params[:sender], class: 'form-control form-control-sm', placeholder: 'From address' %>
+      </div>
+    </div>
+    <div class="col-md-2">
+      <div class="form-group">
+        <label class="small text-muted">Subject</label>
+        <%= text_field_tag :subject_search, params[:subject_search], class: 'form-control form-control-sm', placeholder: 'Subject contains...' %>
+      </div>
+    </div>
+    <div class="col-md-2">
+      <div class="form-group">
+        <label class="small text-muted">Mailer</label>
+        <%= select_tag :mailer, options_for_select([['All', '']] + @mailers.map { |m| [m, m] }, params[:mailer]), class: 'form-control form-control-sm' %>
+      </div>
+    </div>
+    <div class="col-md-2">
+      <div class="form-group">
+        <label class="small text-muted">Status</label>
+        <%= select_tag :status, options_for_select([['All', ''], ['Pending', 'pending'], ['Sent', 'sent'], ['Delivered', 'delivered'], ['Opened', 'opened'], ['Clicked', 'clicked'], ['Bounced', 'bounced'], ['Complained', 'complained']], params[:status]), class: 'form-control form-control-sm' %>
+      </div>
+    </div>
+    <div class="col-md-2 d-flex align-items-end">
+      <div class="form-group w-100">
+        <%= submit_tag 'Filter', class: 'btn btn-primary btn-sm w-100' %>
+      </div>
+    </div>
+  </div>
+  <div class="row">
+    <div class="col-md-2">
+      <div class="form-group">
+        <label class="small text-muted">Date From</label>
+        <%= date_field_tag :date_from, params[:date_from], class: 'form-control form-control-sm' %>
+      </div>
+    </div>
+    <div class="col-md-2">
+      <div class="form-group">
+        <label class="small text-muted">Date To</label>
+        <%= date_field_tag :date_to, params[:date_to], class: 'form-control form-control-sm' %>
+      </div>
+    </div>
+    <div class="col-md-2 d-flex align-items-end">
+      <div class="form-group">
+        <%= link_to 'Clear', mailer_log_engine.admin_emails_path, class: 'btn btn-outline-secondary btn-sm' %>
+      </div>
+    </div>
+  </div>
+<% end %>

data/app/views/mailer_log/admin/emails/index.html.erb

@@ -0,0 +1,61 @@
+<% set_meta_tags title: ['Admin', 'Email Log'] if respond_to?(:set_meta_tags) %>
+
+<div class="card card-border-color card-border-color-dark card-default card-table">
+  <div class="card-header">
+    <span class="title p-a-1">Email Log (<%= @emails.total_count %>)</span>
+  </div>
+  <div class="card-body">
+    <%= render 'filters' %>
+
+    <div class="table-responsive noSwipe">
+      <table class="table table-striped table-hover">
+        <thead>
+          <tr>
+            <th>Sent At</th>
+            <th>Mailer</th>
+            <th>To</th>
+            <th>Subject</th>
+            <th>Status</th>
+            <th></th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @emails.each do |email| %>
+            <%= render 'email', email: email %>
+          <% end %>
+        </tbody>
+      </table>
+
+      <% if @emails.empty? %>
+        <div class="text-center text-muted py-4">
+          No emails found
+        </div>
+      <% end %>
+
+      <% # Use engine routes for pagination %>
+      <div class="pagination-wrapper">
+        <% if @emails.total_pages > 1 %>
+          <nav aria-label="Pagination">
+            <ul class="pagination justify-content-center">
+              <% if @emails.first_page? %>
+                <li class="page-item disabled"><span class="page-link">&laquo; First</span></li>
+                <li class="page-item disabled"><span class="page-link">&lsaquo; Prev</span></li>
+              <% else %>
+                <li class="page-item"><%= link_to '&laquo; First'.html_safe, mailer_log_engine.admin_emails_path(page: 1, per: params[:per]), class: 'page-link' %></li>
+                <li class="page-item"><%= link_to '&lsaquo; Prev'.html_safe, mailer_log_engine.admin_emails_path(page: @emails.prev_page, per: params[:per]), class: 'page-link' %></li>
+              <% end %>
+              <li class="page-item active"><span class="page-link">Page <%= @emails.current_page %> of <%= @emails.total_pages %></span></li>
+              <% if @emails.last_page? %>
+                <li class="page-item disabled"><span class="page-link">Next &rsaquo;</span></li>
+                <li class="page-item disabled"><span class="page-link">Last &raquo;</span></li>
+              <% else %>
+                <li class="page-item"><%= link_to 'Next &rsaquo;'.html_safe, mailer_log_engine.admin_emails_path(page: @emails.next_page, per: params[:per]), class: 'page-link' %></li>
+                <li class="page-item"><%= link_to 'Last &raquo;'.html_safe, mailer_log_engine.admin_emails_path(page: @emails.total_pages, per: params[:per]), class: 'page-link' %></li>
+              <% end %>
+            </ul>
+          </nav>
+        <% end %>
+      </div>
+    </div>
+  </div>
+</div>

data/app/views/mailer_log/admin/emails/show.html.erb

@@ -0,0 +1,132 @@
+<% set_meta_tags title: ['Admin', 'Email Log', @email.subject.presence || 'Email Details'] if respond_to?(:set_meta_tags) %>
+
+<div class="mb-3">
+  <%= link_to mailer_log_engine.admin_emails_path, class: 'btn btn-outline-secondary btn-sm' do %>
+    <i class="far fa-arrow-left"></i> Back to Email Log
+  <% end %>
+</div>
+
+<div class="card card-border-color card-border-color-dark card-default">
+  <div class="card-header">
+    <span class="title"><%= @email.subject.presence || '(no subject)' %></span>
+    <% status_class = case @email.status
+       when 'delivered', 'opened', 'clicked' then 'success'
+       when 'bounced', 'complained' then 'danger'
+       when 'sent' then 'info'
+       else 'secondary'
+       end %>
+    <span class="badge badge-<%= status_class %> float-right"><%= @email.status %></span>
+  </div>
+  <div class="card-body">
+    <div class="row mb-4">
+      <div class="col-md-6">
+        <dl class="row">
+          <dt class="col-sm-3">From</dt>
+          <dd class="col-sm-9"><code><%= @email.from_address %></code></dd>
+
+          <dt class="col-sm-3">To</dt>
+          <dd class="col-sm-9"><code><%= @email.to_addresses.join(', ') %></code></dd>
+
+          <% if @email.cc_addresses.present? %>
+            <dt class="col-sm-3">CC</dt>
+            <dd class="col-sm-9"><code><%= @email.cc_addresses.join(', ') %></code></dd>
+          <% end %>
+
+          <% if @email.bcc_addresses.present? %>
+            <dt class="col-sm-3">BCC</dt>
+            <dd class="col-sm-9"><code><%= @email.bcc_addresses.join(', ') %></code></dd>
+          <% end %>
+
+          <dt class="col-sm-3">Mailer</dt>
+          <dd class="col-sm-9">
+            <code><%= @email.mailer_class %>#<%= @email.mailer_action %></code>
+          </dd>
+
+          <dt class="col-sm-3">Message ID</dt>
+          <dd class="col-sm-9">
+            <code class="small"><%= @email.message_id %></code>
+          </dd>
+
+          <dt class="col-sm-3">Sent At</dt>
+          <dd class="col-sm-9"><%= @email.created_at.strftime('%Y-%m-%d %H:%M:%S %Z') %></dd>
+
+          <% if @email.delivered_at %>
+            <dt class="col-sm-3">Delivered</dt>
+            <dd class="col-sm-9"><%= @email.delivered_at.strftime('%Y-%m-%d %H:%M:%S %Z') %></dd>
+          <% end %>
+
+          <% if @email.opened_at %>
+            <dt class="col-sm-3">Opened</dt>
+            <dd class="col-sm-9"><%= @email.opened_at.strftime('%Y-%m-%d %H:%M:%S %Z') %></dd>
+          <% end %>
+
+          <% if @email.clicked_at %>
+            <dt class="col-sm-3">Clicked</dt>
+            <dd class="col-sm-9"><%= @email.clicked_at.strftime('%Y-%m-%d %H:%M:%S %Z') %></dd>
+          <% end %>
+
+          <% if @email.domain.present? %>
+            <dt class="col-sm-3">Domain</dt>
+            <dd class="col-sm-9"><code><%= @email.domain %></code></dd>
+          <% end %>
+        </dl>
+      </div>
+
+      <div class="col-md-6">
+        <h6>Delivery Events</h6>
+        <% if @email.events.any? %>
+          <table class="table table-sm table-bordered">
+            <thead class="thead-light">
+              <tr>
+                <th>Event</th>
+                <th>Time</th>
+                <th>Recipient</th>
+              </tr>
+            </thead>
+            <tbody>
+              <% @email.events.recent.each do |event| %>
+                <tr>
+                  <td>
+                    <span class="badge badge-<%= event.event_type == 'delivered' ? 'success' : 'secondary' %>">
+                      <%= event.event_type %>
+                    </span>
+                  </td>
+                  <td class="small"><%= event.occurred_at&.strftime('%H:%M:%S') %></td>
+                  <td class="small"><%= event.recipient %></td>
+                </tr>
+              <% end %>
+            </tbody>
+          </table>
+        <% else %>
+          <p class="text-muted small">No delivery events recorded yet.</p>
+        <% end %>
+      </div>
+    </div>
+
+    <h5>Email Preview</h5>
+    <% if @email.html_body.present? %>
+      <iframe src="<%= mailer_log_engine.preview_admin_email_path(@email) %>"
+              class="mailer-log-email-preview"></iframe>
+    <% elsif @email.text_body.present? %>
+      <pre class="bg-light p-3 mailer-log-scrollable-content"><%= @email.text_body %></pre>
+    <% else %>
+      <p class="text-muted">No email body available.</p>
+    <% end %>
+
+    <% if @email.call_stack.present? %>
+      <h5 class="mt-4">Call Stack</h5>
+      <details>
+        <summary class="btn btn-sm btn-outline-secondary mb-2">Show call stack</summary>
+        <pre class="bg-light p-3 small mailer-log-scrollable-content-sm"><%= @email.call_stack %></pre>
+      </details>
+    <% end %>
+
+    <% if @email.headers.present? %>
+      <h5 class="mt-4">Headers</h5>
+      <details>
+        <summary class="btn btn-sm btn-outline-secondary mb-2">Show headers</summary>
+        <pre class="bg-light p-3 small mailer-log-scrollable-content-sm"><%= JSON.pretty_generate(@email.headers) %></pre>
+      </details>
+    <% end %>
+  </div>
+</div>

data/app/views/mailer_log/spa/index.html.erb

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Email Log</title>
+  <% if (css = mailer_log_css_entry) %>
+    <link rel="stylesheet" href="/admin/email_log/<%= css %>">
+  <% else %>
+    <script type="module" src="http://localhost:5173/@vite/client"></script>
+  <% end %>
+</head>
+<body class="bg-gray-100 min-h-screen">
+  <div id="app"></div>
+  <% if (js = mailer_log_js_entry) %>
+    <script type="module" src="/admin/email_log/<%= js %>"></script>
+  <% else %>
+    <script type="module" src="http://localhost:5173/admin/email_log/assets/src/main.js"></script>
+  <% end %>
+</body>
+</html>

data/config/locales/en.yml

@@ -0,0 +1,5 @@
+en:
+  application:
+    nav:
+      titles:
+        emails: Email Log

data/config/routes.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+MailerLog::Engine.routes.draw do
+  # Webhook endpoint for email providers
+  post 'webhooks/mailgun', to: 'webhooks#mailgun'
+
+  # JSON API for Vue frontend
+  namespace :api do
+    resources :emails, only: %i[index show]
+    resources :mailers, only: :index
+  end
+
+  # Static assets for Vue SPA
+  get 'assets/*path', to: 'assets#show', as: :asset, format: false
+
+  # Legacy Admin UI (ERB-based) - keep for email preview iframe
+  namespace :admin do
+    resources :emails, only: %i[index show] do
+      get :preview, on: :member
+    end
+  end
+
+  # SPA catch-all - serves Vue app for all other routes
+  get '/', to: 'spa#index'
+  get '/*path', to: 'spa#index', constraints: ->(req) { !req.path.start_with?('/api', '/admin', '/webhooks', '/assets') }
+end

data/db/schema.rb

@@ -0,0 +1,17 @@
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# This file is the source Rails uses to define your schema when running `bin/rails
+# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
+# be faster and is potentially less error prone than running all of your
+# migrations from scratch. Old migrations may fail to apply correctly if those
+# migrations use external dependencies or application code.
+#
+# It's strongly recommended that you check this file into your version control system.
+
+ActiveRecord::Schema[7.2].define(version: 0) do
+  # These are extensions that must be enabled in order to support this database
+  enable_extension "plpgsql"
+
+end