tempmail_sdk 1.3.4 → 1.3.5

data/lib/tempmail_sdk/providers/tempmailto.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "time"
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # Tempmailto 渠道实现（tempmailto.com，Laravel）
+    #
+    # 前端同款协议：GET / 首页建立 Cookie 会话并从 #mainEmail 的 value
+    # 提取当前邮箱；POST /get_messages（_token=<CSRF>&captcha=）返回
+    # {status, mailbox, email_token, messages, histories}；详情为站内
+    # GET /view/{id}。邮箱约 10 分钟无活动过期，无独立密钥。
+    #
+    # 会话粘性：邮箱由会话 Cookie 承载，Token 约定为邮箱本身（注册表
+    # 以 token 非空作防御）。读到的当前邮箱与请求邮箱不一致时，用
+    # POST /change（_token + name + domain）把会话拉回请求邮箱。
+    # 本端无全局 Cookie 罐，会话 Cookie 由本渠道模块级维护并逐请求
+    # 以显式 Cookie 头回填。
+    module Tempmailto
+      CHANNEL = "tempmailto"
+      BASE_URL = "https://tempmailto.com"
+
+      USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 " \
+                   "(KHTML, like Gecko) Chrome/154.0.0.0 Safari/537.36"
+
+      HOME_ACCEPT = "text/html,application/xhtml+xml,application/xml;q=0.9," \
+                    "image/avif,image/webp,*/*;q=0.8"
+      XHR_ACCEPT = "application/json, text/plain, */*"
+
+      # 模块级会话 Cookie 状态：site => 值，逐请求回填 Cookie 头
+      @cookies = {}
+
+      CSRF_RE = /<meta\s+name="csrf-token"\s+content="([^"]+)"/
+      MAIN_EMAIL_RE = /id="mainEmail"[^>]*\bvalue="([^"]+)"/im
+
+      # 详情正文候选 class（按平台视图页结构依次尝试，后回退 main/article）
+      DETAIL_CLASSES = %w[mail-body mail_content email-body content-body
+                          message-content mail-content].freeze
+
+      module_function
+
+      # 解析 Set-Cookie 头，覆写合并进模块级会话 Cookie 状态
+      # @param resp [Http::Response]
+      def store_cookies(resp)
+        resp.set_cookies.each do |line|
+          kv = line.split(";").first.to_s.strip
+          next if kv.empty?
+
+          k, v = kv.split("=", 2)
+          @cookies[k.strip] = v.to_s if k && !k.strip.empty?
+        end
+      end
+
+      # 由模块级 Cookie 状态拼出显式 Cookie 请求头
+      # @return [String, nil] 无 Cookie 时为 nil
+      def cookie_header
+        return nil if @cookies.empty?
+
+        @cookies.map { |k, v| "#{k}=#{v}" }.join("; ")
+      end
+
+      # 组装浏览器特征请求头（同站调用，照前端实际携带的头）
+      # @param accept [String] Accept 头取值
+      # @param with_cookie [Boolean] 是否回填会话 Cookie
+      # @return [Hash]
+      def browser_headers(accept, with_cookie: true)
+        hdrs = {
+          "User-Agent" => USER_AGENT,
+          "Accept" => accept,
+          "Accept-Language" => "en-US,en;q=0.9",
+          "Origin" => BASE_URL,
+          "Referer" => "#{BASE_URL}/"
+        }
+        hdrs["Cookie"] = cookie_header if with_cookie
+        hdrs.compact
+      end
+
+      # 组装 /get_messages、/change 的 POST 请求头
+      # @return [Hash]
+      def post_headers(accept)
+        hdrs = browser_headers(accept)
+        hdrs["Content-Type"] = "application/x-www-form-urlencoded; charset=UTF-8"
+        hdrs["X-Requested-With"] = "XMLHttpRequest"
+        hdrs
+      end
+
+      # 创建 tempmailto.com 临时邮箱
+      # GET 首页建立会话（响应 Cookie 落入模块级状态）并提取服务端渲染
+      # 的当前邮箱；Token 约定为邮箱本身。邮箱约 10 分钟无活动过期。
+      # @return [EmailInfo]
+      def generate_email
+        resp = Http.get(BASE_URL, headers: browser_headers(HOME_ACCEPT, with_cookie: true), timeout: 15)
+        unless resp.ok?
+          raise "tempmailto: 首页 http #{resp.status_code}"
+        end
+
+        store_cookies(resp)
+        email = ""
+        if (m = resp.body.match(MAIN_EMAIL_RE))
+          email = m[1].strip
+        end
+        if email.empty?
+          raise "tempmailto: 首页未渲染出邮箱（mainEmail 缺失），无法建箱"
+        end
+
+        EmailInfo.new(channel: CHANNEL, email: email, token: email)
+      end
+
+      # 读取 tempmailto.com 当前邮箱的收件箱
+      # 邮箱与请求邮箱不一致时用 change 拉回，再重新读 messages。
+      # @param email [String] 邮箱地址
+      # @param token [String] 渠道会话凭据串（Generate 时约定的邮箱本身）
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        addr = email.to_s.strip
+        if addr.empty?
+          raise "tempmailto: 邮箱为空，请重新 Generate"
+        end
+
+        csrf = fetch_csrf
+        data = fetch_messages(csrf)
+        mailbox = data["mailbox"].to_s.strip
+
+        # 会话粘性：当前邮箱与请求目标不一致 -> change 拉回
+        if !mailbox.empty? && mailbox.casecmp(addr) != 0
+          changed = change_mailbox(addr)
+          if changed.empty?
+            raise "tempmailto: change 响应异常"
+          end
+          if changed.casecmp(addr) != 0
+            raise "tempmailto: 会话邮箱无法拉回请求邮箱"
+          end
+          data = fetch_messages(fetch_csrf)
+        end
+
+        messages = data["messages"]
+        return [] unless messages.is_a?(Array)
+
+        messages.filter_map do |row|
+          next unless row.is_a?(Hash)
+
+          build_email(row, addr)
+        end
+      end
+
+      # GET 首页并提取 CSRF _token（读信/换箱共用，调用同时刷新会话 Cookie）
+      # @return [String]
+      def fetch_csrf
+        resp = Http.get(BASE_URL, headers: browser_headers(HOME_ACCEPT), timeout: 15)
+        store_cookies(resp)
+        m = resp.body.match(CSRF_RE)
+        raise "tempmailto: 首页未找到 csrf-token" unless m
+
+        m[1]
+      end
+
+      # POST /get_messages 拉取当前邮箱的消息 JSON
+      # @param csrf [String] _token 取值
+      # @return [Hash]
+      def fetch_messages(csrf)
+        resp = Http.post("#{BASE_URL}/get_messages",
+                         headers: post_headers(XHR_ACCEPT),
+                         body: "_token=#{csrf}&captcha=", timeout: 15)
+        unless resp.ok?
+          raise "tempmailto 读信: http #{resp.status_code}"
+        end
+        store_cookies(resp)
+
+        data = resp.json
+        raise "tempmailto: 读信响应非对象" unless data.is_a?(Hash)
+
+        data
+      end
+
+      # POST /change 换箱：以请求邮箱的 @ 前部/后部作为 name/domain 拉回会话
+      # @param email [String] 目标邮箱
+      # @return [String] 变更后的当前邮箱（响应 mailbox）
+      def change_mailbox(email)
+        name = email.split("@", 2).first.to_s
+        name = "TmSdk" if name.empty?
+        domain = email.split("@", 2)[1].to_s
+        domain = "tempmailto.com" if domain.empty?
+
+        csrf = fetch_csrf
+        resp = Http.post("#{BASE_URL}/change",
+                         headers: post_headers(XHR_ACCEPT),
+                         body: "_token=#{csrf}&name=#{CGI.escape(name)}&domain=#{CGI.escape(domain)}",
+                         timeout: 15)
+        store_cookies(resp)
+        data = resp.json
+        return "" unless data.is_a?(Hash)
+
+        data["mailbox"].to_s.strip
+      rescue StandardError
+        ""
+      end
+
+      # 将 messages 列表元素组装为统一邮件：
+      # 详情页 /view/{id} 提取正文，失败回退列表字段；id 空跳过。
+      # @param row [Hash] 列表元素
+      # @param email [String] 收件人地址
+      # @return [Email, nil]
+      def build_email(row, email)
+        id = str_of(row["id"])
+        return nil if id.empty?
+
+        html = view_detail(id)
+        text = html.empty? ? "" : HtmlUtils.html_to_text(html)
+        if text.empty?
+          text = str_of(row["body"])
+          text = str_of(row["text"]) if text.empty?
+          text = str_of(row["snippet"]) if text.empty?
+          text = str_of(row["preview"]) if text.empty?
+        end
+        subject = str_of(row["subject"])
+        text = subject if text.empty?
+        html = "<html><body><pre>#{HtmlUtils.escape(text)}</pre></body></html>" if html.empty?
+        date = str_of(row["receivedAt"])
+        date = str_of(row["received_at"]) if date.empty?
+        date = str_of(row["createdAt"]) if date.empty?
+        date = Time.now.utc.iso8601 if date.empty?
+
+        Normalize.normalize_email(normalize_item(row, email, text, html, date), email)
+      end
+
+      # 组装 normalize_email 的入参 Hash（键按本端标准化候选键选取）
+      # @param row [Hash] 列表元素
+      # @param email [String] 收件人地址
+      # @param text [String] 纯文本正文
+      # @param html [String] HTML 正文
+      # @param date [String] 时间
+      # @return [Hash]
+      def normalize_item(row, email, text, html, date)
+        from_email = str_of(row["from_email"])
+        from_email = str_of(row["from"]) if from_email.empty?
+        from_email = str_of(row["from_name"]) if from_email.empty?
+
+        {
+          "id" => str_of(row["id"]),
+          "from_email" => from_email,
+          "to" => email,
+          "subject" => str_of(row["subject"]),
+          "text" => text,
+          "html" => html,
+          "receivedAt" => date,
+          "is_seen" => read_of(row["is_seen"])
+        }
+      end
+
+      # GET /view/{id} 提取邮件正文 HTML（同会话 Cookie，失败返回空串）
+      # @param id [String] 邮件 id
+      # @return [String]
+      def view_detail(id)
+        resp = Http.get("#{BASE_URL}/view/#{URI.encode_www_form_component(id)}",
+                        headers: browser_headers(HOME_ACCEPT), timeout: 15)
+        return "" unless resp.ok?
+
+        store_cookies(resp)
+        extract_detail(resp.body)
+      rescue StandardError
+        ""
+      end
+
+      # 按候选 class 依次提取详情区块，全失败回退 <main>/<article>
+      # @param page [String] 详情页 HTML
+      # @return [String]
+      def extract_detail(page)
+        DETAIL_CLASSES.each do |klass|
+          re = %r{<[^>]+class="[^"]*\b#{Regexp.escape(klass)}\b[^"]*"[^>]*>(.*?)</(?:div|section|article)>}mi
+          m = page.match(re)
+          inner = m && m[1].to_s.strip
+          return inner unless inner.nil? || inner.empty?
+        end
+        if (m = page.match(%r{<(main|article)[^>]*>(.*?)</\1>}mi))
+          inner = m[2].to_s.strip
+          return inner unless inner.empty?
+        end
+        ""
+      end
+
+      # 将接口字段值安全转换为字符串，nil 或非标量返回空串
+      # @param v [Object]
+      # @return [String]
+      def str_of(v)
+        case v
+        when String then v
+        when Numeric then v.to_i.to_s
+        when true then "true"
+        when false then "false"
+        else ""
+        end
+      end
+
+      # 将 is_seen 归一为布尔已读标记，兼容 bool / 数字(0|1) / string("true"|"1")
+      # @param v [Object]
+      # @return [Boolean]
+      def read_of(v)
+        case v
+        when true then true
+        when false then false
+        when Numeric then v != 0
+        when String
+          s = v.strip
+          s.casecmp("true").zero? || s == "1"
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/temporarymail_com.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # Temporarymail 渠道实现（temporarymail.com）
+    #
+    # 无认证 REST（key 为空即随机建箱）：
+    #   GET /api/?action=requestEmailAccess&key=&value=random 建箱，
+    #   响应 {"address":"...","secretKey":"..."}，secretKey 用于后续 checkInbox。
+    # 读信 GET /api/?action=checkInbox&value=<secretKey>，响应有两种形态：
+    #   空收件箱为 []，有信时为 map[id]→邮件元数据对象。
+    # 详情 POST /api/?action=getEmail&value=<id> 覆盖真实主题（列表常为 "[No Subject]"）；
+    # 全文 GET /view/?i=<id> 返回 HTML 化网页，本地剥标签还原纯文本。
+    # 地址最长周期固定为 4 小时。
+    module TemporarymailCom
+      CHANNEL = "temporarymail-com"
+      BASE_URL = "https://temporarymail.com"
+
+      # 备用浏览器 UA（403 重试用，规避共享池随机 UA 耗尽）
+      ALT_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " \
+               "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
+
+      HEADERS = {
+        "Accept" => "application/json, text/plain, */*",
+        "Accept-Language" => "en-US,en;q=0.9",
+        "Sec-Fetch-Site" => "same-origin",
+        "Sec-Fetch-Mode" => "cors",
+        "Sec-Fetch-Dest" => "empty",
+        "Referer" => "#{BASE_URL}/",
+        "Origin" => BASE_URL,
+        "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
+
+      # 构造 /api/ 请求头（403 时换备用 UA 重试）
+      # @param ua [String] User-Agent
+      # @return [Hash]
+      def api_headers(ua)
+        HEADERS.merge("User-Agent" => ua)
+      end
+
+      # 创建 temporarymail.com 临时邮箱
+      # GET /api/?action=requestEmailAccess&key=&value=random；token 复用 secretKey。
+      # @return [EmailInfo]
+      def generate_email
+        resp = Http.get("#{BASE_URL}/api/?action=requestEmailAccess&key=&value=random",
+                        headers: api_headers(HEADERS["User-Agent"]), timeout: 15)
+        if resp.status_code == 429
+          raise "temporarymail: 创建邮箱平台限流(429)，请稍后重试"
+        end
+        resp.raise_for_status
+        data = resp.json
+        raise "temporarymail: 创建响应非对象" unless data.is_a?(Hash)
+
+        addr = data["address"].to_s.strip
+        key = data["secretKey"].to_s.strip
+        raise "temporarymail: 创建响应缺少 address 或 secretKey" if addr.empty? || key.empty?
+
+        EmailInfo.new(channel: CHANNEL, email: addr, token: key)
+      end
+
+      # 解析平台双形态响应（[] 或 map[id]→对象）为数组
+      # @param data [Object] JSON 解析结果
+      # @return [Array<Hash>, nil]
+      def list_of(data)
+        return data if data.is_a?(Array)
+
+        data.values if data.is_a?(Hash)
+      end
+
+      # 读取 temporarymail 收件箱
+      # 列表主题常为 "[No Subject]"：逐封拉详情覆盖真实主题，并逐封抓 /view/ 全文。
+      # @param email [String] 邮箱地址
+      # @param token [String] 建箱返回的 secretKey
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        tk = token.to_s.strip
+        raise "temporarymail: token 为空" if tk.empty?
+
+        body = check_inbox(tk)
+        list = list_of(body)
+        return [] unless list.is_a?(Array)
+
+        addr = email.to_s.strip
+        list.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          row = m.dup
+          row["to"] = addr unless row.key?("to")
+          id = row["id"].to_s.strip
+          unless id.empty?
+            # 详情覆盖真实主题/发件人（失败不致命：列表元数据兜底）
+            det = fetch_detail(id)
+            if det.is_a?(Hash)
+              row["subject"] = det["subject"] if det["subject"].to_s.strip != ""
+              row["from"] = det["from"] if det["from"].to_s.strip != ""
+            end
+            # /view/ 渲染端点全文（失败不致命：列表元数据兜底）
+            text = fetch_view(id)
+            row["text"] = text if !text.empty?
+          end
+          Normalize.normalize_email(row, addr)
+        end
+      end
+
+      # 拉取 checkInbox 响应体；403 换备用 UA 重试一次，429 报平台限流。
+      # @param token [String] secretKey
+      # @return [Object] JSON 解析结果
+      def check_inbox(token)
+        uas = [HEADERS["User-Agent"], ALT_UA]
+        last_status = 0
+        last_raw = ""
+        uas.each do |ua|
+          uri = "#{BASE_URL}/api/?action=checkInbox&value=#{URI.encode_www_form_component(token)}"
+          resp = Http.get(uri, headers: api_headers(ua), timeout: 15)
+          if resp.status_code == 429
+            raise "temporarymail: 读取收件箱平台限流(429)，请拉大轮询间隔"
+          end
+          if resp.ok?
+            return resp.json
+          end
+          last_status = resp.status_code
+          last_raw = resp.body.to_s
+          # 403/404 疑似 UA 键控风控，换备用 UA 重试一次
+          next if [403, 404].include?(resp.status_code)
+
+          raise "temporarymail: 读取收件箱失败 http #{resp.status_code}: #{last_raw}"
+        end
+        raise "temporarymail: 读取收件箱失败 http #{last_status}（两次尝试均被拒）"
+      end
+
+      # 拉取单封详情（POST /api/?action=getEmail&value=<id>），风控失败返回 nil 降级
+      # @param id [String] 邮件 ID
+      # @return [Hash, nil]
+      def fetch_detail(id)
+        uri = "#{BASE_URL}/api/?action=getEmail&value=#{URI.encode_www_form_component(id)}"
+        resp = Http.post(uri, headers: api_headers(HEADERS["User-Agent"]), timeout: 15)
+        return nil if resp.status_code == 429 || !resp.ok?
+
+        data = resp.json
+        return nil unless data.is_a?(Hash)
+
+        data.values.first
+      rescue StandardError
+        nil
+      end
+
+      # 抓取 /view/ 渲染端点全文并还原纯文本
+      # @param id [String] 邮件 ID
+      # @return [String]
+      def fetch_view(id)
+        uri = "#{BASE_URL}/view/?i=#{URI.encode_www_form_component(id)}&width=800"
+        resp = Http.get(uri,
+                        headers: {
+                          "Accept" => "text/html, */*",
+                          "User-Agent" => HEADERS["User-Agent"],
+                          "Referer" => "#{BASE_URL}/"
+                        },
+                        timeout: 15)
+        return "" unless resp.ok?
+
+        view_to_text(resp.body.to_s)
+      end
+
+      # 将 /view/ 响应剥标签还原为纯文本（<br>/<p> 换行保留）
+      # @param src [String] HTML 化网页原文
+      # @return [String]
+      def view_to_text(src)
+        s = src.to_s
+        %w[<br\ /> <br/> <br> <p> </p>].each { |tag| s = s.gsub(tag, "\n") }
+        s = s.gsub(/<script\b[^>]*>.*?<\/script>/mi, " ")
+        s = s.gsub(/<style\b[^>]*>.*?<\/style>/mi, " ")
+        s = s.gsub(/<[^>]+>/, " ")
+        s = s.gsub("&nbsp;", "&").gsub("&nbsp;", " ").gsub("&gt;", ">").gsub("&lt;", "<")
+        s = s.gsub("&quot;", '"').gsub("&#39;", "'").gsub("&amp;", "&")
+        s.split("\n").map { |ln| ln.strip }.join("\n").strip
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/tenmin_app.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  module Providers
+    # Tenmin.app 渠道实现（真实 API 域 api.tenmin.app）
+    #
+    # 建箱+读信共用 GET /api/inbox/{localpart}（Accept: application/json）。
+    # localpart 为随机 6 位小写十六进制串（首访即建箱，平台无显式创建接口）；
+    # 响应：{"inboxId":..,"address":"..@tenmin.app","ttl":600,"count":0,"messages":[]}，
+    # messages[] 元素字段：id/from/subject/text/html/receivedAt（from 为 {name,address} 对象）。
+    module TenminApp
+      CHANNEL = "tenmin-app"
+      BASE_URL = "https://api.tenmin.app"
+      DEFAULT_DOMAIN = "tenmin.app"
+
+      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
+
+      HEX_CHARS = ("0".."9").to_a + ("a".."f").to_a
+
+      # 生成 6 位小写十六进制随机 localpart
+      def random_local
+        Array.new(6) { HEX_CHARS.sample }.join
+      end
+
+      # 请求 /api/inbox/{localpart}
+      # @param localpart [String] 邮箱 localpart
+      # @return [Hash] 解析后的收件箱响应（解析失败返回空 Hash）
+      def fetch_inbox(localpart)
+        resp = Http.get("#{BASE_URL}/api/inbox/#{localpart}", headers: HEADERS, timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        data.is_a?(Hash) ? data : {}
+      end
+
+      # 创建 tenmin.app 临时邮箱
+      # 首次 GET 随机 localpart 即自动建箱（10 分钟 TTL），token 存储 localpart
+      # @return [EmailInfo]
+      def generate_email
+        local = random_local
+        data = fetch_inbox(local)
+        address = data["address"].to_s.strip
+        address = "#{local}@#{DEFAULT_DOMAIN}" if address.empty?
+        ttl = data["ttl"].to_i
+        expires_at = nil
+        expires_at = ((Time.now.to_f + ttl) * 1000).to_i if ttl.positive?
+        EmailInfo.new(channel: CHANNEL, email: address, token: local, expires_at: expires_at)
+      end
+
+      # 读取 tenmin.app 收件箱
+      # 复用建箱同一 localpart 轮询；from 为 {name,address} 对象，拆开格式化后归一。
+      # @param email [String] 邮箱地址
+      # @param token [String] localpart
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        local = token.to_s.strip
+        raise "tenmin-app: token 为空" if local.empty?
+
+        data = fetch_inbox(local)
+        messages = data["messages"]
+        return [] unless messages.is_a?(Array)
+
+        addr = email.to_s.strip
+        messages.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          from = m["from"]
+          # from 为对象（{name,address}）时拆出地址字段
+          from_str = if from.is_a?(Hash)
+                       fname = from["name"].to_s.strip
+                       faddr = from["address"].to_s.strip
+                       if !faddr.empty? && !fname.empty?
+                         "#{fname} <#{faddr}>"
+                       else
+                         faddr.empty? ? fname : faddr
+                       end
+                     else
+                       from.to_s
+                     end
+
+          row = {
+            "id" => m["id"],
+            "from" => from_str,
+            "to" => addr,
+            "subject" => m["subject"],
+            "text" => m["text"],
+            "html" => m["html"],
+            "date" => m["receivedAt"] || m["created_at"] || m["date"]
+          }
+          Normalize.normalize_email(row, addr)
+        end
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/thirty_min_email.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # 30minemail 渠道实现（30minemail.com）
+    #
+    # 官网邮箱由服务端 16 位 hex 本地名识别：
+    #   GET /?generate 返回完整 HTML 页面，从中解析 <地址>@30minemail.com；
+    #   本地名无效邮箱访问 messages.php 时返回 ok:false/expired:true，故必须经服务端建箱。
+    # 读信 GET /messages.php?email=<完整地址>&_=<unix毫秒>，响应
+    #   {"ok":true,"expired":false,"count":0,"emails":[],"expires_in":...}。
+    # emails 元素字段实测：{id,from,to,subject,date,html}（html 为完整正文）。
+    # 无认证、无 Cookie、无 CSRF。
+    module ThirtyMinEmail
+      CHANNEL = "30minemail"
+      BASE_URL = "https://30minemail.com"
+      DOMAIN = "30minemail.com"
+
+      HEADERS = {
+        "Accept" => "text/html,application/xhtml+xml,application/json;q=0.9,*/*;q=0.8",
+        "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
+
+      # 创建 30minemail.com 临时邮箱
+      # GET /?generate 返回 HTML 页面，从其中解析 16 位 hex 本地名地址；
+      # token 复用完整地址（服务端以地址定位收件箱）。
+      # @return [EmailInfo]
+      def generate_email
+        resp = Http.get("#{BASE_URL}/?generate", headers: HEADERS, timeout: 15)
+        resp.raise_for_status
+        page = resp.body.to_s
+        idx = page.index("@#{DOMAIN}")
+        raise "30minemail: 创建页面未找到邮箱地址" if idx.nil?
+
+        # 向前查找本地名起点：空白或 > 之后
+        start = idx
+        while start.positive? && ![" ", "\n", "\t", ">", '"'].include?(page[start - 1])
+          start -= 1
+        end
+        local = page[start...idx].to_s.strip
+        raise "30minemail: 创建页面解析地址异常" if local.length < 8
+
+        addr = "#{local}@#{DOMAIN}"
+        EmailInfo.new(channel: CHANNEL, email: addr, token: addr)
+      end
+
+      # 读取 30minemail.com 收件箱
+      # GET /messages.php?email=<完整地址>&_=<unix毫秒>，模拟官方轮询参数。
+      # @param email [String] 完整邮箱地址
+      # @param token [String] 复用完整地址（服务端以地址定位收件箱）
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        addr = email.to_s.strip
+        raise "30minemail: 邮箱地址为空" if addr.empty?
+
+        uri = "#{BASE_URL}/messages.php?email=#{URI.encode_www_form_component(addr)}&_=#{(Time.now.to_f * 1000).to_i}"
+        resp = Http.get(uri,
+                        headers: {
+                          "Accept" => "application/json",
+                          "User-Agent" => HEADERS["User-Agent"]
+                        },
+                        timeout: 15)
+        raise "30minemail: 读取收件箱失败 http #{resp.status_code}" unless resp.ok?
+
+        data = resp.json
+        raise "30minemail: 收件箱响应非对象" unless data.is_a?(Hash)
+
+        unless data["ok"] == true && data["expired"] != true
+          raise "30minemail: 收件箱不可用或已过期"
+        end
+        emails = data["emails"]
+        return [] unless emails.is_a?(Array)
+
+        emails.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          row = m.dup
+          # 列表元素无 to 字段时注入收件人地址
+          row["to"] = addr unless row.key?("to")
+          Normalize.normalize_email(row, addr)
+        end
+      end
+    end
+  end
+end