tempmail_sdk 1.3.4 → 1.3.5

data/lib/tempmail_sdk/providers/nukemail.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "digest"
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # Nukemail 渠道实现（nukemail.app）
+    #
+    # 完整接入契约：
+    #   挑战 GET /api/pow/challenge?difficulty=4 → 200 {"id","challenge","difficulty"}；
+    #     求 nonce 使 SHA-256(challenge+nonce) 十六进制前 4 位为 0
+    #     （前端 solvePow 逐 nonce 自 0 递增）。
+    #   建箱 POST /api/inbox/create body {"address","domain","pow_id","pow_nonce"}
+    #     → 200 {"token":"NUKE-xxxxxxxx","email":"名@域名"}，并
+    #     Set-Cookie: nukemail_token=<token>（Secure; HttpOnly; SameSite=lax, 72h）。
+    #   读信 GET /api/inbox（Cookie: nukemail_token=<token>）→ 200
+    #     {"token","state","addresses":[...],"messages":[...],"is_premium"...}；
+    #     messages 元素字段为 sender、sender_name、subject、body_html、body_text、
+    #     received_at、read。
+    #   会话恢复 POST /api/inbox/resume {"accessCode":<token>} 重设 Cookie，仅作兜底。
+    # 会话隔离：nukemail_token 由生成结果持久化为 token，读信时以显式 Cookie 头携带。
+    module Nukemail
+      CHANNEL = "nukemail"
+      BASE_URL = "https://nukemail.app"
+
+      HEADERS = {
+        "Accept" => "application/json",
+        "User-Agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " \
+                        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
+      }.freeze
+
+      module_function
+
+      # 求解 PoW：返回使 SHA-256(challenge+nonce) 十六进制
+      # 前 difficulty 位为 0 的最小 nonce（算法与前端 solvePow 逐字对齐）。
+      # @param challenge [String] 挑战串
+      # @param difficulty [Integer] 难度（十六进制前缀 0 位数）
+      # @return [Integer] nonce
+      def solve_pow(challenge, difficulty)
+        prefix = "0" * difficulty
+        nonce = 0
+        loop do
+          digest = Digest::SHA256.hexdigest("#{challenge}#{nonce}")
+          break if digest.start_with?(prefix)
+
+          nonce += 1
+        end
+        nonce
+      end
+
+      # 生成本地随机名（与前端 generateRandomName 等价形态）
+      # @return [String]
+      def random_address
+        chars = "abcdefghijklmnopqrstuvwxyz0123456789"
+        "nuke" + Array.new(10) { chars[rand(chars.length)] }.join
+      end
+
+      # 取第一个非 premium 的活跃域名
+      # @return [String]
+      def default_domain
+        resp = Http.get("#{BASE_URL}/api/domains", headers: HEADERS, timeout: 15)
+        raise "nukemail generate: domains http #{resp.status_code}" unless resp.ok?
+
+        data = resp.json
+        domains = data.is_a?(Hash) ? data["domains"] : nil
+        raise "nukemail generate: domains 响应非对象" unless domains.is_a?(Array)
+
+        domains.each do |d|
+          next unless d.is_a?(Hash)
+
+          dom = d["domain"].to_s.strip
+          return dom if !dom.empty? && d["is_premium_only"] != true
+        end
+        raise "nukemail generate: 无可用非 premium 域名"
+      end
+
+      # 创建临时邮箱（PoW 建箱）
+      # token 为平台返回的 NUKE-<随机> 访问码，读信时转成 nukemail_token Cookie 携带。
+      # @return [EmailInfo]
+      def generate_email
+        # 1) 取 PoW 挑战
+        resp = Http.get("#{BASE_URL}/api/pow/challenge?difficulty=4",
+                        headers: HEADERS, timeout: 15)
+        raise "nukemail generate: challenge http #{resp.status_code}" unless resp.ok?
+
+        ch = resp.json
+        raise "nukemail generate: challenge 响应非对象" unless ch.is_a?(Hash)
+
+        ch_id = ch["id"].to_s.strip
+        challenge = ch["challenge"].to_s.strip
+        raise "nukemail generate: challenge 响应缺少 id/challenge" if ch_id.empty? || challenge.empty?
+
+        difficulty = ch["difficulty"].to_i
+        difficulty = 4 if difficulty <= 0
+
+        # 2) 本地求 PoW 解（SHA-256 前缀 4 零）
+        nonce = solve_pow(challenge, difficulty)
+
+        # 3) 取域名并建箱
+        dom = default_domain
+        body = {
+          "address" => random_address,
+          "domain" => dom,
+          "pow_id" => ch_id,
+          "pow_nonce" => nonce.to_s
+        }
+        headers = {
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "User-Agent" => HEADERS["User-Agent"]
+        }
+        resp2 = Http.post("#{BASE_URL}/api/inbox/create",
+                          headers: headers, json: body, timeout: 15)
+        unless resp2.ok?
+          raise "nukemail generate: create http #{resp2.status_code}"
+        end
+        data = resp2.json
+        raise "nukemail generate: create 响应非对象" unless data.is_a?(Hash)
+
+        token = data["token"].to_s.strip
+        email = data["email"].to_s.strip
+        raise "nukemail generate: create 响应缺少 token/email" if token.empty? || email.empty?
+
+        EmailInfo.new(channel: CHANNEL, email: email, token: token)
+      end
+
+      # 读取收件箱
+      # 主通道 GET /api/inbox 带 Cookie: nukemail_token=<token>；
+      # 会话过期时经 POST /api/inbox/resume 显式重设会话后重试一次。
+      # @param email [String] 邮箱地址
+      # @param token [String] 建箱返回的 NUKE-<随机> 访问码
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        addr = email.to_s.strip
+        tk = token.to_s.strip
+        raise "nukemail: token 为空" if tk.empty?
+
+        cookie = "nukemail_token=#{tk}"
+
+        fetch = lambda do
+          resp = Http.get("#{BASE_URL}/api/inbox",
+                          headers: HEADERS.merge("Cookie" => cookie), timeout: 15)
+          raise "nukemail 读信: http #{resp.status_code}" unless resp.ok?
+
+          resp.json
+        end
+
+        data = fetch.call
+        raise "nukemail 读信: 响应非对象" unless data.is_a?(Hash)
+
+        if data["state"].to_s.empty? || data["state"] == "expired"
+          # 会话可能已过期：经 resume 重设会话后重试
+          headers = {
+            "Content-Type" => "application/json",
+            "User-Agent" => HEADERS["User-Agent"]
+          }
+          begin
+            Http.post("#{BASE_URL}/api/inbox/resume",
+                      headers: headers, json: { "accessCode" => tk }, timeout: 15)
+          rescue StandardError
+            nil
+          end
+          data = fetch.call
+          raise "nukemail 读信: 响应非对象" unless data.is_a?(Hash)
+        end
+
+        messages = data["messages"]
+        return [] unless messages.is_a?(Array)
+
+        messages.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          flat = m.dup
+          flat["to"] = addr
+          # 平台消息字段为 body_html/body_text，补齐 text/html 候选（若原字段缺失）
+          flat["text"] = flat["body_text"] if flat["text"].nil?
+          flat["html"] = flat["body_html"] if flat["html"].nil?
+          flat["date"] = m["received_at"]
+          flat["read"] = m["read"]
+          # sender 是小写发件人地址，sender_name 是展示名
+          flat["sender_email"] = m["sender"]
+          Normalize.normalize_email(flat, addr)
+        end
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/nullmail.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # Nullmail 渠道实现（nullmail.cc / maildock.store）
+    #
+    # 无认证 REST：
+    #   POST /api/emails（空 JSON body）建箱，响应
+    #   {"address":"...@maildock.store","expiry":"2026-09-27T02:25:28.778Z"}；
+    #   GET /api/emails/{address}（URL 编码）读信，响应 {"expiry":"...","emails":[...]}，
+    #   列表项只有 id/sender/subject/delivered，正文须逐封二拉 GET /api/emails/{addr}/body/{id}
+    #   （响应 {"body":...}）。
+    module Nullmail
+      CHANNEL = "nullmail"
+      BASE_URL = "https://www.nullmail.cc"
+      DOMAIN = "maildock.store"
+
+      HEADERS = {
+        "Accept" => "application/json",
+        "Origin" => BASE_URL,
+        "Referer" => "#{BASE_URL}/",
+        "User-Agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " \
+                        "(KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36 Edg/146.0.0.0"
+      }.freeze
+
+      module_function
+
+      # 创建 nullmail 临时邮箱
+      # POST /api/emails（空 JSON body），token 复用完整地址以便收件箱回查
+      # @return [EmailInfo]
+      def generate_email
+        resp = Http.post("#{BASE_URL}/api/emails",
+                         headers: HEADERS.merge("Content-Type" => "application/json"),
+                         json: {}, timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        addr = data.is_a?(Hash) ? data["address"].to_s.strip : ""
+        raise "nullmail: 建箱响应缺少 address 字段" if addr.empty?
+
+        EmailInfo.new(channel: CHANNEL, email: addr, token: addr,
+                      expires_at: data["expiry"])
+      end
+
+      # 单封正文二拉
+      # GET /api/emails/{addr}/body/{id}，响应 {"body":"<完整纯文本正文>"}
+      # @param addr [String] 邮箱地址
+      # @param id [Object] 邮件 ID
+      # @return [String]
+      def fetch_body(addr, id)
+        uri = "#{BASE_URL}/api/emails/#{URI.encode_www_form_component(addr)}" \
+              "/body/#{URI.encode_www_form_component(id.to_s)}"
+        resp = Http.get(uri, headers: HEADERS, timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        data.is_a?(Hash) ? data["body"].to_s : ""
+      end
+
+      # 读取收件箱
+      # GET /api/emails/{address}（完整地址 URL 编码），列表项无正文，逐封二拉 body 端点；
+      # 正文拉取失败降级留空不阻断列表。
+      # @param email [String] 邮箱地址
+      # @param _token [String] 令牌（本渠道忽略，以邮箱为准）
+      # @return [Array<Email>]
+      def get_emails(email, _token)
+        addr = email.to_s.strip
+        raise "nullmail: 邮箱地址为空" if addr.empty?
+
+        uri = "#{BASE_URL}/api/emails/#{URI.encode_www_form_component(addr)}"
+        resp = Http.get(uri, headers: HEADERS, timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        emails = data.is_a?(Hash) ? data["emails"] : nil
+        return [] unless emails.is_a?(Array)
+
+        emails.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          row = {
+            "id" => m["id"],
+            "from" => m["sender"] || m["from"],
+            "to" => addr,
+            "subject" => m["subject"],
+            # 列表只有 id/sender/subject/delivered，delivered 显式映射为 date
+            "date" => m["delivered"] || m["date"]
+          }
+          body = fetch_body(addr, m["id"]) if m["id"]
+          row["text"] = body unless body.to_s.empty?
+          Normalize.normalize_email(row, addr)
+        end
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/shadowmail.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  module Providers
+    # Shadowmail 渠道实现（shadowmail.win）
+    #
+    # 完整接入契约：
+    #   注册 POST /api/register {"email":"<随机前缀>@gmail.com","password":"Abcd1234!"}
+    #     → 200 {"message":"Successfully Registered"}；
+    #   登录 POST /api/login → 200 {"message":"Successfull Login"}
+    #     并 Set-Cookie: sessionId=<uuid>（HttpOnly; Secure; Max-Age 3600）；
+    #   建箱 POST /api/new-address → 200 {...,"address":"<id>@shadowmail.win","id":<id>}；
+    #   读信 POST /api/get-emails {"address":"<地址>"} → 200 {"message":"Emails read",
+    #     "mails":[...]}；mails 元素字段 id/address_id/sender/subject/body/created_at。
+    # 会话隔离：全域使用显式 Cookie 头（sessionId=<uuid>），凭据串 token 持久化
+    #   注册邮箱/密码/会话 id，便于会话过期后自动重生。
+    module Shadowmail
+      CHANNEL = "shadowmail"
+      BASE_URL = "https://shadowmail.win"
+      # 固定注册密码（平台无自选密码入口，注册即固定）
+      PW = "Abcd1234!"
+      # 平台唯一收信域
+      DOMAIN = "shadowmail.win"
+      # 本渠道凭据串前缀
+      TOKEN_PREFIX = "shadowmail|"
+
+      HEADERS = {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " \
+                        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
+      }.freeze
+
+      module_function
+
+      # 生成随机注册邮箱前缀（sdk+8 位小写字母）
+      # @return [String]
+      def random_account
+        chars = "abcdefghijklmnopqrstuvwxyz"
+        "sdk" + Array.new(8) { chars[rand(chars.length)] }.join
+      end
+
+      # 携带显式 Cookie 的 JSON POST 请求，返回 [body, status, set_cookies]
+      # @param path [String] 请求路径
+      # @param body [Hash] JSON 请求体
+      # @param cookie [String] Cookie 头（可为空）
+      # @return [Array(Array, Integer, Array<String>)]
+      def do_post(path, body, cookie)
+        headers = HEADERS.dup
+        headers["Cookie"] = cookie unless cookie.to_s.empty?
+        resp = Http.post("#{BASE_URL}#{path}", headers: headers, json: body, timeout: 15)
+        [resp.json, resp.status_code, resp.set_cookies]
+      end
+
+      # 从 Set-Cookie 中提取 sessionId 值（纯 uuid，不含键名）
+      # @param cookies [Array<String>]
+      # @return [String]
+      def session_from(cookies)
+        cookies.each do |line|
+          kv = line.split(";").first.to_s.strip
+          return kv.split("=", 2)[1].to_s if kv.start_with?("sessionId=")
+        end
+        ""
+      end
+
+      # 注册或登录（POST /api/register、/api/login），返回会话 sessionId
+      # @param account [String] 注册邮箱
+      # @param password [String] 密码
+      # @param is_login [Boolean] true 走登录，false 走注册
+      # @return [String] sessionId 值
+      def register_login(account, password, is_login)
+        path = is_login ? "/api/login" : "/api/register"
+        body = { "email" => account, "password" => password }
+        data, status, cookies = do_post(path, body, "")
+        raise "shadowmail #{path}: http #{status}" if status < 200 || status >= 300
+
+        msg = data.is_a?(Hash) ? data["message"].to_s : ""
+        if is_login
+          raise "shadowmail login: #{msg}" unless msg == "Successfull Login"
+        else
+          # 重复注册（幂等）：消息为 Email already in use 时视为账号已存在，继续走登录
+          unless ["Successfully Registered", "Email already in use"].include?(msg)
+            raise "shadowmail register: #{msg}"
+          end
+        end
+        session = session_from(cookies)
+        if is_login && session.empty?
+          raise "shadowmail login: 未下发 sessionId Cookie"
+        end
+        session
+      end
+
+      # 注册账号并创建临时邮箱地址
+      # @return token 凭据串格式："shadowmail|<account>|<password>|<sessionId>"
+      # @return [EmailInfo]
+      def generate_email
+        account = "#{random_account}@gmail.com"
+
+        # 1) 注册（幂等：已存在同名账号则跳过）
+        register_login(account, PW, false)
+        # 2) 登录取得 sessionId
+        session = register_login(account, PW, true)
+        # 3) 创建地址（每账号 12 槽）：SDK 层显式 Cookie 头传 sessionId
+        data, status, = do_post("/api/new-address", {}, "sessionId=#{session}")
+        raise "shadowmail new-address: http #{status}" if status < 200 || status >= 300
+
+        address = data.is_a?(Hash) ? data["address"].to_s.strip : ""
+        raise "shadowmail new-address: 响应缺少有效地址" unless address.end_with?("@#{DOMAIN}")
+
+        # Token 持久化：account|password|sessionId（sessionId 为 uuid，无分隔符冲突）
+        token = TOKEN_PREFIX + [account, PW, session].join("|")
+        EmailInfo.new(channel: CHANNEL, email: address.downcase.strip, token: token)
+      end
+
+      # 解析凭据串为 account/password/sessionId 三元组
+      # @param token [String]
+      # @return [Array(String, String, String)]
+      def parse_token(token)
+        raise "shadowmail: token 格式错误" unless token.to_s.start_with?(TOKEN_PREFIX)
+
+        parts = token.to_s[TOKEN_PREFIX.length..].to_s.split("|", -1)
+        raise "shadowmail: token 字段缺失" unless parts.length == 3
+
+        account, password, session = parts
+        raise "shadowmail: token 凭据字段为空" if account.empty? || password.empty? || session.empty?
+
+        [account, password, session]
+      end
+
+      # 读取收件箱
+      # 会话失效时自动以凭据内 account/password 重新登录换新 sessionId。
+      # @param email [String] 平台新地址（<id>@shadowmail.win）
+      # @param token [String] 建箱下发的凭据串
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        account, password, session = parse_token(token)
+        addr = email.to_s.strip
+
+        do_fetch = lambda do
+          do_post("/api/get-emails", { "address" => addr }, "sessionId=#{session}")
+        end
+
+        data, status, = do_fetch.call
+        # sessionId 最长 1 小时（Max-Age 3600），过期后重登录重试一次
+        if status == 401 || status == 404
+          new_session = register_login(account, password, true)
+          unless new_session.empty?
+            session = new_session
+            data, status, = do_fetch.call
+          end
+        end
+        raise "shadowmail get-emails: http #{status}" if status < 200 || status >= 300
+
+        msg = data.is_a?(Hash) ? data["message"].to_s : ""
+        raise "shadowmail get-emails: #{msg}" unless msg == "Emails read"
+
+        mails = data.is_a?(Hash) ? data["mails"] : nil
+        return [] unless mails.is_a?(Array)
+
+        mails.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          flat = m.dup
+          flat["from"] = m["sender"]
+          flat["to"] = addr
+          flat["date"] = m["created_at"]
+          # 平台无 text/html 区分，body 为正文（默认按纯文本处理，普通化可按需互转）
+          flat["text"] = m["body"]
+          Normalize.normalize_email(flat, addr)
+        end
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/shitpost_email.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # shitpost.email 渠道实现（公共实例，克隆自 shamu4life/throwaway-email）
+    #
+    # 无认证 REST：
+    #   POST /api/create 建箱（username/domain/ttl → email/token/type/expires）
+    #   GET /api/inbox?email=&token= 读信（messages[] 含 from/fromName/subject/text/html/date）
+    # 域名池：shitpost.email / letsfuckingpiss.party
+    module ShitpostEmail
+      CHANNEL = "shitpost-email"
+      BASE_URL = "https://shitpost.email"
+      DOMAINS = %w[shitpost.email letsfuckingpiss.party].freeze
+
+      HEADERS = {
+        "Accept" => "application/json",
+        "User-Agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " \
+                        "(KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36 Edg/146.0.0.0"
+      }.freeze
+
+      module_function
+
+      # 生成 "sdk"+10 位 [a-z0-9] 随机用户名
+      CHARS = ("a".."z").to_a + ("0".."9").to_a
+      def random_username
+        "sdk" + Array.new(10) { CHARS.sample }.join
+      end
+
+      # 创建临时邮箱
+      # POST /api/create，body 为 {username, domain, ttl}
+      # @return [EmailInfo]
+      def generate_email
+        body = { "username" => random_username, "domain" => DOMAINS.sample, "ttl" => 3600 }
+        resp = Http.post("#{BASE_URL}/api/create",
+                         headers: HEADERS.merge("Content-Type" => "application/json"),
+                         json: body, timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        email = data.is_a?(Hash) ? data["email"].to_s.strip : ""
+        token = data.is_a?(Hash) ? data["token"].to_s.strip : ""
+        raise "shitpost-email: 建箱响应缺少 email 或 token" if email.empty? || token.empty?
+
+        EmailInfo.new(channel: CHANNEL, email: email, token: token,
+                      expires_at: data["expires"])
+      end
+
+      # 读取收件箱
+      # GET /api/inbox?email=&token=
+      # @param email [String] 邮箱地址
+      # @param token [String] 建箱返回的令牌
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        addr = email.to_s.strip
+        tk = token.to_s
+        raise "shitpost-email: token 为空" if tk.strip.empty?
+
+        url = "#{BASE_URL}/api/inbox?email=#{URI.encode_www_form_component(addr)}" \
+              "&token=#{URI.encode_www_form_component(tk)}"
+        resp = Http.get(url, headers: HEADERS, timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        messages = data.is_a?(Hash) ? data["messages"] : nil
+        return [] unless messages.is_a?(Array)
+
+        messages.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          row = {
+            "id" => m["id"],
+            "from" => m["from"],
+            "to" => addr,
+            "subject" => m["subject"],
+            "text" => m["text"],
+            "html" => m["html"],
+            "date" => m["date"]
+          }
+          Normalize.normalize_email(row, addr)
+        end
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/smails.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # smails.dev 渠道实现
+    #
+    # 流程：
+    #   POST /api/mailbox 建箱（空 JSON body，响应 address/token）
+    #   GET /api/mailbox/messages 读信（Header Authorization: Bearer <token>，数组响应）
+    #   GET /api/mailbox/messages/{id} 取单封详情（Bearer）
+    # 列表元素按 from/subject/text/html/date 多候选归一；详情拉取失败时以列表摘要兜底。
+    module Smails
+      CHANNEL = "smails"
+      BASE_URL = "https://smails.dev"
+
+      HEADERS = {
+        "Accept" => "application/json",
+        "User-Agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " \
+                        "(KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36 Edg/146.0.0.0"
+      }.freeze
+
+      # 可行 ID 候选键，按序提取（结果转为字符串）
+      ID_KEYS = %w[id Id slug messageId message_id].freeze
+
+      module_function
+
+      # 设置 smails.dev 请求的通用请求头
+      # @param token [String] 认证令牌，非空时携带 Authorization: Bearer
+      # @return [Hash]
+      def auth_headers(token = "")
+        hdrs = HEADERS.dup
+        hdrs["Authorization"] = "Bearer #{token}" unless token.to_s.empty?
+        hdrs
+      end
+
+      # 创建 smails.dev 临时邮箱
+      # POST /api/mailbox（空 JSON body）返回 address 与 token
+      # @return [EmailInfo]
+      def generate_email
+        resp = Http.post("#{BASE_URL}/api/mailbox",
+                         headers: HEADERS.merge("Content-Type" => "application/json"),
+                         json: {}, timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        address = data.is_a?(Hash) ? data["address"].to_s.strip : ""
+        token = data.is_a?(Hash) ? data["token"].to_s.strip : ""
+        raise "smails: 创建邮箱响应缺少必要字段" if address.empty? || token.empty?
+
+        EmailInfo.new(channel: CHANNEL, email: address, token: token)
+      end
+
+      # 获取 smails.dev 邮件列表
+      # GET /api/mailbox/messages；对每个元素按 id 逐封请求详情合并，失败时以摘要归一。
+      # @param token [String] Bearer 令牌
+      # @param email [String] 邮箱地址
+      # @return [Array<Email>]
+      def get_emails(token, email)
+        tk = token.to_s.strip
+        raise "smails: token 为空" if tk.empty?
+
+        resp = Http.get("#{BASE_URL}/api/mailbox/messages", headers: auth_headers(tk), timeout: 15)
+        resp.raise_for_status
+        list = resp.json
+        return [] unless list.is_a?(Array)
+
+        addr = email.to_s.strip
+        list.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          Normalize.normalize_email(detail_row(tk, m, addr), addr)
+        end
+      end
+
+      # 从列表元素中提取消息 ID（候选键 id/Id/slug/messageId/message_id）
+      # @param row [Hash]
+      # @return [String]
+      def message_id_of(row)
+        ID_KEYS.each do |key|
+          val = row[key]
+          return val.to_s.strip unless val.nil? || val.to_s.strip.empty?
+        end
+        ""
+      end
+
+      # 逐封拉取详情并合并到列表摘要；无 ID 或详情失败时以摘要归一
+      # @param token [String] Bearer 令牌
+      # @param summary [Hash] 列表元素摘要
+      # @param email [String] 收件人邮箱
+      # @return [Hash] 归一化输入行
+      def detail_row(token, summary, email)
+        id = message_id_of(summary)
+        uri = "#{BASE_URL}/api/mailbox/messages/#{URI.encode_www_form_component(id)}"
+        resp = Http.get(uri, headers: auth_headers(token), timeout: 15)
+        merged = summary
+        if resp.ok?
+          detail = begin
+            resp.json
+          rescue StandardError
+            nil
+          end
+          # 详情缺失字段不覆盖列表摘要（包含 null 的键跳过）
+          merged = summary.merge(detail.reject { |_k, v| v.nil? }) if detail.is_a?(Hash)
+        end
+        to_normalized_row(merged, email)
+      rescue StandardError
+        to_normalized_row(summary, email)
+      end
+
+      # 将原始消息 Hash 转换为归一化输入行
+      # @param raw [Hash]
+      # @param email [String]
+      # @return [Hash]
+      def to_normalized_row(raw, email)
+        {
+          "id" => raw["id"] || raw["messageId"] || raw["message_id"],
+          "from" => raw["from"],
+          "to" => email,
+          "subject" => raw["subject"],
+          "text" => raw["text"],
+          "html" => raw["html"],
+          "date" => raw["date"]
+        }
+      end
+    end
+  end
+end