mailscope 0.1.0

data/app/views/mailscope/shared/_icons.html.erb

@@ -0,0 +1,58 @@
+<svg class="ms-sprite" aria-hidden="true" focusable="false">
+  <defs>
+    <symbol id="i-search" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/>
+    </symbol>
+    <symbol id="i-inbox" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M4 13h4l2 3h4l2-3h4"/><path d="M5 5h14l1.5 8v4a2 2 0 0 1-2 2h-13a2 2 0 0 1-2-2v-4z"/>
+    </symbol>
+    <symbol id="i-trash" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M4 7h16"/><path d="M10 11v6M14 11v6"/><path d="M6 7l1 12a2 2 0 0 0 2 2h6a2 2 0 0 0 2-2l1-12"/><path d="M9 7V5a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2"/>
+    </symbol>
+    <symbol id="i-refresh" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M20 11a8 8 0 1 0-2.3 6.3"/><path d="M20 5v6h-6"/>
+    </symbol>
+    <symbol id="i-clip" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M17 8.5 9.4 16a2.8 2.8 0 0 0 4 4l7.2-7.4a4.7 4.7 0 0 0-6.6-6.6L6.3 13.7a6.6 6.6 0 0 0 9.3 9.3"/>
+    </symbol>
+    <symbol id="i-download" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M12 4v10"/><path d="m8 11 4 4 4-4"/><path d="M5 19h14"/>
+    </symbol>
+    <symbol id="i-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M2 12h2M20 12h2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M19.1 4.9l-1.4 1.4M6.3 17.7l-1.4 1.4"/>
+    </symbol>
+    <symbol id="i-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M20 14.5A8.5 8.5 0 1 1 9.5 4a6.8 6.8 0 0 0 10.5 10.5z"/>
+    </symbol>
+    <symbol id="i-desktop" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <rect x="3" y="4" width="18" height="12" rx="2"/><path d="M8 20h8M12 16v4"/>
+    </symbol>
+    <symbol id="i-mobile" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <rect x="7" y="3" width="10" height="18" rx="2"/><path d="M11 18h2"/>
+    </symbol>
+    <symbol id="i-tablet" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <rect x="5" y="3" width="14" height="18" rx="2"/><path d="M11 18h2"/>
+    </symbol>
+    <symbol id="i-shield" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M12 3l7 3v6c0 4.5-3 7.8-7 9-4-1.2-7-4.5-7-9V6z"/><path d="m9 12 2 2 4-4"/>
+    </symbol>
+    <symbol id="i-eye" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M2 12s3.6-6 10-6 10 6 10 6-3.6 6-10 6-10-6-10-6z"/><circle cx="12" cy="12" r="2.5"/>
+    </symbol>
+    <symbol id="i-envelope" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <rect x="3" y="5.5" width="18" height="13" rx="2"/><path d="m3.4 6.6 8.6 6 8.6-6"/>
+    </symbol>
+    <symbol id="i-menu" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M4 7h16M4 12h16M4 17h16"/>
+    </symbol>
+    <symbol id="i-close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M6 6l12 12M18 6 6 18"/>
+    </symbol>
+    <symbol id="i-keyboard" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <rect x="2" y="6" width="20" height="12" rx="2"/><path d="M6 10h.01M10 10h.01M14 10h.01M18 10h.01M6 14h12"/>
+    </symbol>
+    <symbol id="i-external" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M14 4h6v6"/><path d="M20 4 10 14"/><path d="M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5"/>
+    </symbol>
+  </defs>
+</svg>

data/config/locales/mailscope.en.yml

@@ -0,0 +1,105 @@
+en:
+  mailscope:
+    search:
+      placeholder: "Search by subject, sender or recipient…"
+      label: "Search messages"
+    actions:
+      refresh: "Refresh"
+      refresh_hint: "Refresh (r)"
+      live: "Live"
+      live_hint: "Automatically checks for newly delivered mail"
+      theme: "Toggle theme"
+      shortcuts: "Shortcuts"
+      shortcuts_hint: "Shortcuts (?)"
+      clear: "Clear"
+      clear_confirm: "Delete every captured message? This cannot be undone."
+      clear_filters: "clear filters"
+      clear_filters_button: "Clear filters"
+      delete: "Delete"
+      delete_hint: "Delete (x)"
+      delete_message: "Delete %{subject}"
+      download: "Download .eml"
+      open_in_tab: "Open in a new tab"
+      open_preview: "Open the preview"
+      allow_remote: "Load anyway"
+      close: "Close"
+    rail:
+      heading: "Mailboxes"
+      label: "Mailboxes"
+      all: "All messages"
+      empty: "No recipients yet."
+    list:
+      label: "Messages"
+      listbox: "Message list"
+      count:
+        one: "message"
+        other: "messages"
+      to: "to %{list}"
+      unknown_sender: "unknown sender"
+      attachments:
+        one: "1 attachment"
+        other: "%{count} attachments"
+    empty:
+      no_results_title: "Nothing found"
+      no_results_text: "No message matches these filters."
+      inbox_title: "Empty inbox"
+      inbox_text: "Send an email from your app and it shows up here."
+      no_selection_title: "No message selected"
+      no_selection_text_html: "Pick a message on the left, or send a new one from your app.<br>Use %{keys} to move around and %{search} to search."
+    message:
+      no_subject: "(no subject)"
+      bcc: "Bcc"
+      to_line: "to %{list}"
+      preview_label: "Message preview"
+      loading: "Loading…"
+      source_error: "Could not load the message source."
+      empty_part: "This message has no content in this version."
+    tabs:
+      html: "HTML"
+      text: "Text"
+      source: "Source"
+      headers: "Headers"
+      attachments: "Attachments"
+    preview:
+      widths: "Preview width"
+      desktop: "Desktop"
+      tablet: "Tablet"
+      mobile: "Mobile"
+      remote_content: "Remote content"
+      remote_hint: "Blocks images and media loaded from external servers"
+      blocked_html:
+        one: "<strong>1</strong> external resource blocked in this message."
+        other: "<strong>%{count}</strong> external resources blocked in this message."
+    toasts:
+      deleted: "Message deleted."
+      delete_failed: "Could not delete the message."
+      cleared:
+        one: "1 message deleted."
+        other: "%{count} messages deleted."
+      clear_failed: "Could not clear the inbox."
+      new_mail: "New mail arrived."
+      open: "Open"
+      list_failed: "Could not refresh the list."
+      open_failed: "Could not open that message."
+      theme: "Theme: %{name}"
+      theme_system: "system"
+      theme_light: "light"
+      theme_dark: "dark"
+    shortcuts:
+      title: "Shortcuts"
+      next: "Next message"
+      previous: "Previous message"
+      search: "Search"
+      refresh: "Refresh the list"
+      delete: "Delete the selected message"
+      tabs: "Switch tabs"
+      theme: "Toggle theme"
+      help: "This help"
+      close: "Close"
+    time:
+      now: "now"
+      minutes: "%{count} min"
+      datetime: "%m/%d/%Y at %H:%M:%S"
+      weekdays: [Sun, Mon, Tue, Wed, Thu, Fri, Sat]
+    storage:
+      imported: "Message imported from letter_opener"

data/config/locales/mailscope.pt-BR.yml

@@ -0,0 +1,105 @@
+pt-BR:
+  mailscope:
+    search:
+      placeholder: "Buscar por assunto, remetente ou destinatário…"
+      label: "Buscar mensagens"
+    actions:
+      refresh: "Atualizar"
+      refresh_hint: "Atualizar (r)"
+      live: "Ao vivo"
+      live_hint: "Verifica automaticamente se chegaram mensagens novas"
+      theme: "Alternar tema"
+      shortcuts: "Atalhos"
+      shortcuts_hint: "Atalhos (?)"
+      clear: "Limpar"
+      clear_confirm: "Apagar todas as mensagens capturadas? Isso não tem volta."
+      clear_filters: "limpar filtros"
+      clear_filters_button: "Limpar filtros"
+      delete: "Apagar"
+      delete_hint: "Apagar (x)"
+      delete_message: "Apagar %{subject}"
+      download: "Baixar .eml"
+      open_in_tab: "Abrir em nova aba"
+      open_preview: "Abrir a pré-visualização"
+      allow_remote: "Carregar mesmo assim"
+      close: "Fechar"
+    rail:
+      heading: "Caixas"
+      label: "Caixas de e-mail"
+      all: "Todas as mensagens"
+      empty: "Nenhum destinatário ainda."
+    list:
+      label: "Mensagens"
+      listbox: "Lista de mensagens"
+      count:
+        one: "mensagem"
+        other: "mensagens"
+      to: "para %{list}"
+      unknown_sender: "remetente desconhecido"
+      attachments:
+        one: "1 anexo"
+        other: "%{count} anexos"
+    empty:
+      no_results_title: "Nada encontrado"
+      no_results_text: "Nenhuma mensagem bate com esses filtros."
+      inbox_title: "Caixa vazia"
+      inbox_text: "Envie um e-mail pela aplicação e ele aparece aqui."
+      no_selection_title: "Nenhuma mensagem selecionada"
+      no_selection_text_html: "Escolha uma mensagem à esquerda, ou envie uma nova pela aplicação.<br>Use %{keys} para navegar e %{search} para buscar."
+    message:
+      no_subject: "(sem assunto)"
+      bcc: "Cco"
+      to_line: "para %{list}"
+      preview_label: "Pré-visualização da mensagem"
+      loading: "Carregando…"
+      source_error: "Não consegui carregar a fonte da mensagem."
+      empty_part: "Esta mensagem não tem conteúdo nesta versão."
+    tabs:
+      html: "HTML"
+      text: "Texto"
+      source: "Fonte"
+      headers: "Cabeçalhos"
+      attachments: "Anexos"
+    preview:
+      widths: "Largura do preview"
+      desktop: "Desktop"
+      tablet: "Tablet"
+      mobile: "Mobile"
+      remote_content: "Conteúdo remoto"
+      remote_hint: "Bloqueia imagens e mídia carregadas de servidores externos"
+      blocked_html:
+        one: "<strong>1</strong> recurso externo bloqueado nesta mensagem."
+        other: "<strong>%{count}</strong> recursos externos bloqueados nesta mensagem."
+    toasts:
+      deleted: "Mensagem apagada."
+      delete_failed: "Não consegui apagar a mensagem."
+      cleared:
+        one: "1 mensagem apagada."
+        other: "%{count} mensagens apagadas."
+      clear_failed: "Não consegui limpar a caixa."
+      new_mail: "Chegou mensagem nova."
+      open: "Abrir"
+      list_failed: "Falha ao atualizar a lista."
+      open_failed: "Não consegui abrir essa mensagem."
+      theme: "Tema: %{name}"
+      theme_system: "automático"
+      theme_light: "claro"
+      theme_dark: "escuro"
+    shortcuts:
+      title: "Atalhos"
+      next: "Próxima mensagem"
+      previous: "Mensagem anterior"
+      search: "Buscar"
+      refresh: "Atualizar a lista"
+      delete: "Apagar a mensagem selecionada"
+      tabs: "Trocar de aba"
+      theme: "Alternar tema"
+      help: "Esta ajuda"
+      close: "Fechar"
+    time:
+      now: "agora"
+      minutes: "%{count} min"
+      datetime: "%d/%m/%Y às %H:%M:%S"
+      weekdays: [Dom, Seg, Ter, Qua, Qui, Sex, Sáb]
+    storage:
+      imported: "Mensagem importada do letter_opener"

data/config/routes.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+Mailscope::Engine.routes.draw do
+  root to: 'messages#index'
+
+  get 'status', to: 'messages#status', as: :status
+
+  scope 'messages' do
+    delete '/', to: 'messages#clear', as: :clear_messages
+
+    scope ':id', constraints: { id: /[0-9a-zA-Z_-]+/ } do
+      get    '/',                    to: 'messages#show', as: :message
+      delete '/',                    to: 'messages#destroy'
+      get    'body',                 to: 'messages#body',       as: :message_body
+      get    'source',               to: 'messages#source',     as: :message_source
+      get    'download',             to: 'messages#download',   as: :message_download
+      get    'attachments/:attachment_id', to: 'messages#attachment', as: :message_attachment,
+                                           constraints: { attachment_id: /[0-9]+/ }
+    end
+  end
+
+  get 'assets/:digest/:file', to: 'assets#show', as: :asset,
+                              constraints: { file: /[\w-]+\.(css|js|svg|woff2)/, digest: /[0-9a-f]+/ }
+end

data/lib/mailscope/body_renderer.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'cgi'
+
+module Mailscope
+  # Builds the document that goes inside the preview iframe.
+  #
+  # The body is never rewritten with blind gsubs the way letter_opener_web
+  # did it. Inline (cid:) images become data: URIs so the frame can stay in a
+  # fully sandboxed opaque origin, and everything else is controlled with a
+  # Content-Security-Policy response header rather than by editing the markup.
+  class BodyRenderer
+    MAX_INLINE_BYTES = 2 * 1024 * 1024
+    REMOTE_ASSET = /\b(?:src|background)\s*=\s*["']?\s*https?:/i
+    REMOTE_CSS_ASSET = /url\(\s*["']?\s*https?:/i
+    URL_IN_TEXT = %r{\bhttps?://[^\s<>"')\]]+}
+
+    attr_reader :message, :part, :block_remote, :theme
+
+    def initialize(message, part: nil, block_remote: true, theme: 'light')
+      @message      = message
+      @part         = %w[html text].include?(part.to_s) ? part.to_s : message.default_part
+      @block_remote = block_remote
+      @theme        = theme.to_s == 'dark' ? 'dark' : 'light'
+    end
+
+    def dark? = theme == 'dark'
+
+    def document
+      <<~HTML
+        <!doctype html>
+        <html lang="pt-BR">
+        <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <base target="_blank">
+        <style>#{frame_styles}</style>
+        </head>
+        <body class="mailscope-frame mailscope-frame--#{part} mailscope-frame--#{theme}">#{body}</body>
+        </html>
+      HTML
+    end
+
+    def content_security_policy
+      directives = [
+        "default-src 'none'",
+        "style-src 'unsafe-inline' data:",
+        'font-src data:',
+        "frame-src 'none'",
+        "object-src 'none'",
+        "script-src 'none'",
+        "form-action 'none'",
+        "base-uri 'none'"
+      ]
+      directives << (block_remote ? 'img-src data:' : 'img-src data: https: http:')
+      directives << (block_remote ? "media-src 'none'" : 'media-src data: https: http:')
+      directives.join('; ')
+    end
+
+    # How many remote assets the current policy is holding back. Surfaced in
+    # the UI so "why is this email blank?" answers itself.
+    def blocked_resources
+      return 0 unless block_remote
+
+      @blocked_resources ||= raw_body.to_s.scan(REMOTE_ASSET).size + raw_body.to_s.scan(REMOTE_CSS_ASSET).size
+    end
+
+    def empty? = raw_body.to_s.strip.empty?
+
+    private
+
+    def raw_body
+      @raw_body ||= part == 'html' ? message.html_body : message.text_body
+    end
+
+    def body
+      if empty?
+        message = CGI.escapeHTML(Mailscope.translate('message.empty_part', 'This message has no content in this version.'))
+        return %(<p class="mailscope-empty">#{message}</p>)
+      end
+
+      part == 'html' ? html_body : text_body
+    end
+
+    def html_body
+      inline_cid_images(raw_body)
+    end
+
+    def text_body
+      escaped = CGI.escapeHTML(raw_body)
+      linked  = escaped.gsub(URL_IN_TEXT) { |url| %(<a href="#{url}">#{url}</a>) }
+      %(<pre class="mailscope-plain">#{linked}</pre>)
+    end
+
+    def inline_cid_images(html)
+      html.gsub(/cid:([^"'\s>)]+)/i) do
+        cid = Regexp.last_match(1)
+        data_uri_for(cid) || "cid:#{cid}"
+      end
+    end
+
+    def data_uri_for(cid)
+      needle = cid.delete_prefix('<').delete_suffix('>')
+      attachment = message.attachments.find { |a| a.cid.to_s.delete_prefix('<').delete_suffix('>') == needle }
+      return nil unless attachment && attachment.size.to_i <= MAX_INLINE_BYTES
+
+      bytes = message.attachment_body(attachment.id)
+      return nil unless bytes
+
+      "data:#{attachment.content_type};base64,#{Base64.strict_encode64(bytes)}"
+    end
+
+    # The HTML part is deliberately left on white: it is the message exactly as
+    # its recipients will see it, and inverting it would both misrepresent the
+    # design and fight with emails that ship their own prefers-color-scheme
+    # rules. The plain-text part has no sender design to preserve, so it
+    # follows the app's theme like the Source and Headers views do.
+    def frame_styles
+      <<~CSS
+        html { background: #{page_background}; }
+        body { margin: 0; padding: 20px; color: #{page_text}; background: #{page_background};
+               font: 14px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; }
+        img { max-width: 100%; height: auto; }
+        a { color: #{link_color}; }
+        .mailscope-plain { margin: 0; white-space: pre-wrap; word-break: break-word;
+                           font: 13px/1.6 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+        .mailscope-empty { color: #{muted_color}; font-style: italic; }
+      CSS
+    end
+
+    def themed? = part == 'text' && dark?
+
+    def page_background = themed? ? '#12151c' : '#fff'
+
+    def page_text = themed? ? '#e7e9f0' : '#111'
+
+    def muted_color = themed? ? '#7b8296' : '#6b7280'
+
+    def link_color = themed? ? '#8b8cf5' : '#0b57d0'
+  end
+end

data/lib/mailscope/configuration.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mailscope
+  # Runtime configuration. Set through `Mailscope.configure`.
+  class Configuration
+    # Where captured mail is stored. Accepts anything Pathname() understands.
+    attr_reader :location
+
+    # Storage adapter: a symbol registered in Mailscope::Storage, or an object
+    # responding to the Mailscope::Storage::Base interface.
+    attr_accessor :storage
+
+    # Retention. Both are applied after every delivery; nil disables the check.
+    attr_accessor :max_letters, :max_age
+
+    # Callable receiving the ActionDispatch::Request. Return a falsy value to
+    # deny access. Nil means the UI is open to anyone who can reach the route.
+    attr_accessor :authenticate_with
+
+    # Default state of the "block remote content" switch in the preview pane.
+    attr_accessor :block_remote_content
+
+    # Polling for newly delivered mail, in the browser. Off by default: the
+    # user turns it on from the header and the choice sticks per browser.
+    attr_accessor :auto_refresh, :auto_refresh_interval
+
+    # :system, :light or :dark. The user can override it in the UI.
+    attr_accessor :default_theme
+
+    # Shown in the header and the <title>.
+    attr_accessor :title
+
+    # Widths offered by the viewport switcher, in CSS pixels.
+    attr_accessor :preview_widths
+
+    def initialize
+      @location             = default_location
+      @storage              = :filesystem
+      @max_letters          = 500
+      @max_age              = nil
+      @authenticate_with    = nil
+      @block_remote_content = true
+      @auto_refresh         = false
+      @auto_refresh_interval = 3
+      @default_theme        = :system
+      @title                = 'Mailscope'
+      @preview_widths       = { 'Desktop' => nil, 'Tablet' => 768, 'Mobile' => 390 }
+    end
+
+    def location=(value)
+      @location = Pathname(value.to_s)
+    end
+
+    # letter_opener_web compatibility, so an existing initializer keeps working.
+    alias letters_location location
+    alias letters_location= location=
+
+    private
+
+    def default_location
+      root = defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+      Pathname(root ? root.join('tmp', 'mailscope').to_s : File.join(Dir.tmpdir, 'mailscope'))
+    end
+  end
+end

data/lib/mailscope/delivery_method.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Mailscope
+  # ActionMailer delivery method. Unlike letter_opener it stores the raw
+  # message plus a small metadata index, and never shells out to a browser.
+  class DeliveryMethod
+    attr_accessor :settings
+
+    def initialize(settings = {})
+      self.settings = settings
+    end
+
+    def deliver!(mail)
+      validate!(mail)
+
+      id = storage.store(mail)
+      prune
+      id
+    end
+
+    private
+
+    def storage
+      settings[:storage] || Mailscope.storage
+    end
+
+    def prune
+      storage.prune(max_letters: Mailscope.config.max_letters, max_age: Mailscope.config.max_age)
+    rescue StandardError => e
+      Mailscope.logger.warn("[mailscope] retention pass failed: #{e.class}: #{e.message}")
+    end
+
+    def validate!(mail)
+      if blank_envelope?(mail.smtp_envelope_from)
+        raise ArgumentError,
+              'An SMTP From address is required to deliver a message.'
+      end
+      raise ArgumentError, 'An SMTP To address is required to deliver a message.' if blank_envelope?(mail.smtp_envelope_to)
+    end
+
+    def blank_envelope?(value)
+      Array(value).reject { |v| v.to_s.strip.empty? }.empty?
+    end
+  end
+end

data/lib/mailscope/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'mailscope/delivery_method'
+
+module Mailscope
+  class Engine < ::Rails::Engine
+    isolate_namespace Mailscope
+
+    initializer 'mailscope.delivery_method' do
+      ActiveSupport.on_load :action_mailer do
+        ActionMailer::Base.add_delivery_method(:mailscope, Mailscope::DeliveryMethod)
+        # Accept the old name too, so a fork migration is a one-line change.
+        ActionMailer::Base.add_delivery_method(:letter_opener_web, Mailscope::DeliveryMethod)
+      end
+    end
+
+    initializer 'mailscope.default_location' do
+      Mailscope.config.location = Rails.root.join('tmp', 'mailscope') if Mailscope.config.location.to_s.empty?
+    end
+  end
+end

data/lib/mailscope/mailbox.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Mailscope
+  # A recipient address, with the messages that landed in it. This is what the
+  # left rail lists: one entry per "caixa de e-mail".
+  # rubocop:disable Lint/StructNewOverride -- `count` reads better than any
+  # alternative here, and this struct is never used as an enumerable.
+  Mailbox = Struct.new(:address, :name, :count, :latest_at, keyword_init: true) do
+    def label = name.to_s.empty? ? address : name
+
+    def initials
+      source = label.to_s
+      letters = source.scan(/[[:alnum:]]+/).first(2).map { |w| w[0] }.join
+      (letters.empty? ? source[0, 2] : letters).to_s.upcase
+    end
+
+    # Stable colour per mailbox, so the same address always looks the same.
+    def hue = address.to_s.each_byte.sum % 360
+
+    def to_h = { address:, name:, count:, latest_at: latest_at&.iso8601 }
+
+    def self.index(messages)
+      buckets = {}
+      messages.each { |message| message.recipients.each { |addr| absorb(buckets, addr, message) } }
+      buckets.values.sort_by { |box| [-box.latest_at.to_i, box.address] }
+    end
+
+    def self.absorb(buckets, addr, message)
+      key = addr.address.to_s.downcase
+      return if key.empty?
+
+      box = buckets[key] ||= new(address: key, name: addr.name, count: 0, latest_at: nil)
+      box.name ||= addr.name
+      box.count += 1
+      box.latest_at = message.sent_at if box.latest_at.nil? || message.sent_at > box.latest_at
+    end
+  end
+  # rubocop:enable Lint/StructNewOverride
+end