tempmail_sdk 1.3.3

data/lib/tempmail_sdk/channels_data.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+#
+# 渠道元数据（有序，权威来源 .channel_meta.json，顺序与 baseline 逐行一致）
+# 每项为 [slug, name, website]，注册表按此顺序枚举，顺序为硬约束。
+#
+module TempmailSdk
+  # 279 个渠道的有序元数据
+  CHANNEL_DATA = [
+    ["tempmail", "TempMail", "tempmail.ing"],
+    ["tempmail-cn", "TempMail CN", "tempmail.cn"],
+    ["ta-easy", "TA Easy", "ta-easy.com"],
+    ["10minute-one", "10 Minute Email", "10minutemail.one"],
+    ["xghff-com", "xghff.com", "10minutemail.one"],
+    ["oqqaj-com", "oqqaj.com", "10minutemail.one"],
+    ["psovv-com", "psovv.com", "10minutemail.one"],
+    ["dbwot-com", "dbwot.com", "10minutemail.one"],
+    ["ygwpr-com", "ygwpr.com", "10minutemail.one"],
+    ["imxwe-com", "imxwe.com", "10minutemail.one"],
+    ["linshiyou", "临时邮", "linshiyou.com"],
+    ["mffac", "MFFAC", "mffac.com"],
+    ["tempmail-lol", "TempMail LOL", "tempmail.lol"],
+    ["chatgpt-org-uk", "ChatGPT Mail", "mail.chatgpt.org.uk"],
+    ["temp-mail-io", "Temp-Mail.io", "temp-mail.io"],
+    ["mail-cx", "Mail.cx", "mail.cx"],
+    ["ddker-com", "ddker.com", "mail.cx"],
+    ["catchmail", "Catchmail", "catchmail.io"],
+    ["catchmail-mailistry", "Catchmail Mailistry", "mailistry.com"],
+    ["catchmail-zeppost", "Catchmail Zeppost", "zeppost.com"],
+    ["mailforspam", "MailForSpam", "mailforspam.com"],
+    ["mailforspam-tempmail-io", "MailForSpam TempMail.io", "tempmail.io"],
+    ["mailforspam-disposable", "MailForSpam Disposable", "disposable.email"],
+    ["tempmailc", "TempMailC", "tempmailc.com"],
+    ["mailnesia", "Mailnesia", "mailnesia.com"],
+    ["throwawaymail", "ThrowawayMail", "throwawaymail.app"],
+    ["tempmail-fish", "TempMail Fish", "tempmail.fish"],
+    ["neighbours-sh", "Neighbours", "neighbours.sh"],
+    ["shitty-email", "shitty.email", "shitty.email"],
+    ["tempmailpro", "TempMail Pro", "tempmailpro.us"],
+    ["devmail-uk", "DevMail UK", "devmail.uk"],
+    ["inboxkitten", "InboxKitten", "inboxkitten.com"],
+    ["cleantempmail", "CleanTempMail", "cleantempmail.com"],
+    ["getnada", "GetNada", "getnada.net"],
+    ["1vpn-net", "1vpn.net", "getnada.net"],
+    ["abematv-com", "abematv.com", "getnada.net"],
+    ["abematv-net", "abematv.net", "getnada.net"],
+    ["abematv-org", "abematv.org", "getnada.net"],
+    ["aceh-cc", "aceh.cc", "getnada.net"],
+    ["bangkabelitung-net", "bangkabelitung.net", "getnada.net"],
+    ["cctruyen-com", "cctruyen.com", "getnada.net"],
+    ["getnada-com", "getnada.com", "getnada.net"],
+    ["getnada-email", "getnada.email", "getnada.net"],
+    ["getnada-net", "getnada.net", "getnada.net"],
+    ["jawatengah-net", "jawatengah.net", "getnada.net"],
+    ["jawatimur-net", "jawatimur.net", "getnada.net"],
+    ["kalimantanbarat-net", "kalimantanbarat.net", "getnada.net"],
+    ["kalimantanselatan-net", "kalimantanselatan.net", "getnada.net"],
+    ["kalimantantengah-net", "kalimantantengah.net", "getnada.net"],
+    ["kalimantantimur-net", "kalimantantimur.net", "getnada.net"],
+    ["kalimantanutara-net", "kalimantanutara.net", "getnada.net"],
+    ["kepulauanriau-net", "kepulauanriau.net", "getnada.net"],
+    ["luxury345-com", "luxury345.com", "getnada.net"],
+    ["malukuutara-net", "malukuutara.net", "getnada.net"],
+    ["nusatenggarabarat-net", "nusatenggarabarat.net", "getnada.net"],
+    ["nusatenggaratimur-net", "nusatenggaratimur.net", "getnada.net"],
+    ["papuabarat-net", "papuabarat.net", "getnada.net"],
+    ["papuabaratdaya-net", "papuabaratdaya.net", "getnada.net"],
+    ["papuaselatan-net", "papuaselatan.net", "getnada.net"],
+    ["pehol-com", "pehol.com", "getnada.net"],
+    ["ptruyen-com", "ptruyen.com", "getnada.net"],
+    ["pulaubali-net", "pulaubali.net", "getnada.net"],
+    ["riau-net", "riau.net", "getnada.net"],
+    ["seokey-org", "seokey.org", "getnada.net"],
+    ["sulawesibarat-net", "sulawesibarat.net", "getnada.net"],
+    ["sulawesiselatan-net", "sulawesiselatan.net", "getnada.net"],
+    ["sulawesitengah-net", "sulawesitengah.net", "getnada.net"],
+    ["sulawesitenggara-net", "sulawesitenggara.net", "getnada.net"],
+    ["sumaterabarat-net", "sumaterabarat.net", "getnada.net"],
+    ["sumateraselatan-net", "sumateraselatan.net", "getnada.net"],
+    ["sumaterautara-net", "sumaterautara.net", "getnada.net"],
+    ["villatogel-com", "villatogel.com", "getnada.net"],
+    ["mail123", "Mail123", "mail123.fr"],
+    ["mail10s", "Mail10s", "mail10s.com"],
+    ["webmailtemp", "WebMailTemp", "webmailtemp.com"],
+    ["tempfastmail", "TempFastMail", "tempfastmail.com"],
+    ["1sec-mail", "1SecMail", "1sec-mail.com"],
+    ["fakemail", "FakeMail", "fakemail.net"],
+    ["openinbox", "OpenInbox", "openinbox.io"],
+    ["inboxes", "Inboxes", "inboxes.com"],
+    ["uncorreotemporal", "UnCorreoTemporal", "uncorreotemporal.com"],
+    ["awamail", "AwaMail", "awamail.com"],
+    ["mail-tm", "Mail.tm", "mail.tm"],
+    ["web-library-net", "web-library.net", "mail.tm"],
+    ["dropmail", "DropMail", "dropmail.me"],
+    ["guerrillamail", "Guerrilla Mail", "guerrillamail.com"],
+    ["guerrillamail-com", "GuerrillaMail Root", "guerrillamail.com"],
+    ["maildrop", "Maildrop", "maildrop.cx"],
+    ["smail-pw", "Smail.pw", "smail.pw"],
+    ["vip-215", "VIP 215", "vip.215.im"],
+    ["fake-legal", "Fake Legal", "fake.legal"],
+    ["imgui-de", "imgui.de", "fake.legal"],
+    ["pulsewebmenu-de", "pulsewebmenu.de", "fake.legal"],
+    ["moakt", "Moakt", "moakt.com"],
+    ["drmail-in", "drmail.in", "moakt.com"],
+    ["teml-net", "teml.net", "moakt.com"],
+    ["tmpeml-com", "tmpeml.com", "moakt.com"],
+    ["tmpbox-net", "tmpbox.net", "moakt.com"],
+    ["moakt-cc", "moakt.cc", "moakt.com"],
+    ["disbox-net", "disbox.net", "moakt.com"],
+    ["tmpmail-org", "tmpmail.org", "moakt.com"],
+    ["tmpmail-net", "tmpmail.net", "moakt.com"],
+    ["tmails-net", "tmails.net", "moakt.com"],
+    ["disbox-org", "disbox.org", "moakt.com"],
+    ["moakt-co", "moakt.co", "moakt.com"],
+    ["moakt-ws", "moakt.ws", "moakt.com"],
+    ["tmail-ws", "tmail.ws", "moakt.com"],
+    ["bareed-ws", "bareed.ws", "moakt.com"],
+    ["email10min", "Email10Min", "email10min.com"],
+    ["mjj-cm", "MJJ Mail", "mjj.cm"],
+    ["linshi-co", "临时Co", "linshi.co"],
+    ["harakirimail", "HarakiriMail", "harakirimail.com"],
+    ["jqkjqk-xyz", "jqkjqk.xyz", "mail.zhujump.com"],
+    ["lyhlevi-com", "LyhLevi MoeMail", "lyhlevi.com"],
+    ["tempmail-plus", "TempMail Plus", "tempmail.plus"],
+    ["fexpost-com", "fexpost.com", "tempmail.plus"],
+    ["fexbox-org", "fexbox.org", "tempmail.plus"],
+    ["mailbox-in-ua", "mailbox.in.ua", "tempmail.plus"],
+    ["rover-info", "rover.info", "tempmail.plus"],
+    ["chitthi-in", "chitthi.in", "tempmail.plus"],
+    ["fextemp-com", "fextemp.com", "tempmail.plus"],
+    ["any-pink", "any.pink", "tempmail.plus"],
+    ["merepost-com", "merepost.com", "tempmail.plus"],
+    ["tempmail-lol-v2", "TempMail LOL V2", "tempmail.lol"],
+    ["tempgbox", "TempGBox", "tempgbox.net"],
+    ["emailnator", "Emailnator", "emailnator.com"],
+    ["temporam", "Temporam", "temporam.com"],
+    ["neighbours", "Neighbours", "neighbours.sh"],
+    ["sharklasers", "SharkLasers", "sharklasers.com"],
+    ["sharklasers-com", "SharkLasers Root", "sharklasers.com"],
+    ["grr-la", "Grr.la", "grr.la"],
+    ["grr-la-com", "Grr.la Root", "grr.la"],
+    ["guerrillamail-info", "GuerrillaMail Info", "guerrillamail.info"],
+    ["spam4me", "Spam4.me", "spam4.me"],
+    ["guerrillamail-net", "GuerrillaMail Net", "guerrillamail.net"],
+    ["guerrillamail-org", "GuerrillaMail Org", "guerrillamail.org"],
+    ["guerrillamailblock", "GuerrillaMailBlock", "guerrillamailblock.com"],
+    ["guerrillamail-com-www", "GuerrillaMail WWW", "guerrillamail.com"],
+    ["m2u", "MailToYou", "m2u.io"],
+    ["tempy-email", "Tempy Email", "tempy.email"],
+    ["fmail", "FMail", "fmail.men"],
+    ["ockito", "Ockito", "ockito.com"],
+    ["anonbox", "Anonbox", "anonbox.net"],
+    ["duckmail", "DuckMail", "duckmail.sbs"],
+    ["mailinator", "Mailinator", "mailinator.com"],
+    ["tempmail365", "Tempmail365", "https://tempmail365.cn"],
+    ["tempinbox", "TempInbox", "https://www.tempinbox.xyz"],
+    ["byom", "Byom", "byom.de"],
+    ["anonymmail", "AnonymMail", "anonymmail.net"],
+    ["eyepaste", "EyePaste", "eyepaste.com"],
+    ["mail-sunls", "Mail Sunls", "mail.sunls.de"],
+    ["expressinboxhub", "ExpressInboxHub", "expressinboxhub.com"],
+    ["lroid", "Lroid", "lroid.com"],
+    ["haribu", "Haribu", "haribu.net"],
+    ["rootsh", "Rootsh(BccTo)", "rootsh.com"],
+    ["fake-email-site", "FakeEmailSite", "fake-email.site"],
+    ["mohmal", "Mohmal", "mohmal.com"],
+    ["mailgolem", "MailGolem", "mailgolem.com"],
+    ["best-temp-mail", "BestTempMail", "best-temp-mail.com"],
+    ["disposablemail-app", "DisposableMail", "disposablemail.app"],
+    ["mailtemp-cc", "MailTemp.cc", "mailtemp.cc"],
+    ["minuteinbox", "MinuteInbox", "minuteinbox.com"],
+    ["mailcatch", "MailCatch", "mailcatch.com"],
+    ["tempemail-co", "TempEmail.co", "tempemail.co"],
+    ["tempemails-net", "TempEmails.net", "tempemails.net"],
+    ["altmails", "AltMails", "tempmail.altmails.com"],
+    ["tempemail-info", "TempEmailInfo", "tempemail.info"],
+    ["smailpro", "SmailPro", "smailpro.com"],
+    ["tempmailten", "TempMailTen", "tempmailten.com"],
+    ["maildrop-cc", "MailDrop.cc", "maildrop.cc"],
+    ["10minutemail-net", "10MinuteMail.net", "10minutemail.net"],
+    ["linshiyouxiang-net", "临时邮箱(linshiyouxiang)", "linshiyouxiang.net"],
+    ["tempmail-fyi", "Temp-Mail.fyi", "temp-mail.fyi"],
+    ["disposablemail-com", "DisposableMail.com", "disposablemail.com"],
+    ["tempp-mails", "TemppMails", "tempp-mails.com"],
+    ["emailtemp-org", "EmailTemp", "emailtemp.org"],
+    ["mytempmail-cc", "MyTempMail.cc", "mytempmail.cc"],
+    ["temp-mail-now", "TempMailNow", "temp-mail.now"],
+    ["mail-td", "Mail.td", "mail.td"],
+    ["mailhole-de", "Mailhole.de", "mailhole.de"],
+    ["tmail-link", "TMail.link", "tmail.link"],
+    ["24mail-chacuo", "24Mail Chacuo", "24mail.chacuo.net"],
+    ["nimail", "NiMail", "nimail.cn"],
+    ["freecustom", "FreeCustom.Email", "freecustom.email"],
+    ["16888888-cyou", "Mailmomy (16888888.cyou)", "mailmomy.com"],
+    ["17666688-shop", "Mailmomy (17666688.shop)", "mailmomy.com"],
+    ["282mail-com", "Mailmomy (282mail.com)", "mailmomy.com"],
+    ["blackhole-djurby-se", "Mailinator (blackhole.djurby.se)", "mailinator.com"],
+    ["block-bdea-cc", "Mailinator (block.bdea.cc)", "mailinator.com"],
+    ["bsdu32-buzz", "Mailmomy (bsdu32.buzz)", "mailmomy.com"],
+    ["b-smelly-cc", "Mailinator (b.smelly.cc)", "mailinator.com"],
+    ["carlton183-changeip-net", "Mailinator (183carlton.changeip.net)", "mailinator.com"],
+    ["dea-soon-it", "Mailinator (dea.soon.it)", "mailinator.com"],
+    ["disposable-al-sudani-com", "Mailinator (disposable.al-sudani.com)", "mailinator.com"],
+    ["disposable-nogonad-nl", "Mailinator (disposable.nogonad.nl)", "mailinator.com"],
+    ["doxu243-buzz", "Mailmomy (doxu243.buzz)", "mailmomy.com"],
+    ["easyme-pro", "Mailmomy (easyme.pro)", "mailmomy.com"],
+    ["ebs-com-ar", "Mailinator (ebs.com.ar)", "mailinator.com"],
+    ["etgdev-de", "Mailinator (etgdev.de)", "mailinator.com"],
+    ["evergreenco-shop", "Mailmomy (evergreenco.shop)", "mailmomy.com"],
+    ["fwd2m-eszett-es", "Mailinator (fwd2m.eszett.es)", "mailinator.com"],
+    ["jama-trenet-eu", "Mailinator (jama.trenet.eu)", "mailinator.com"],
+    ["j-fairuse-org", "Mailinator (j.fairuse.org)", "mailinator.com"],
+    ["layueming-pics", "Mailmomy (layueming.pics)", "mailmomy.com"],
+    ["m-887-at", "Mailinator (m.887.at)", "mailinator.com"],
+    ["m8r-davidfuhr-de", "Mailinator (m8r.davidfuhr.de)", "mailinator.com"],
+    ["m8r-mcasal-com", "Mailinator (m8r.mcasal.com)", "mailinator.com"],
+    ["mail-bentrask-com", "Mailinator (mail.bentrask.com)", "mailinator.com"],
+    ["mail-fsmash-org", "Mailinator (mail.fsmash.org)", "mailinator.com"],
+    ["mailinatorzz-mooo-com", "Mailinator (mailinatorzz.mooo.com)", "mailinator.com"],
+    ["mi-meon-be", "Mailinator (mi.meon.be)", "mailinator.com"],
+    ["mingyuekeji-online", "Mailmomy (mingyuekeji.online)", "mailmomy.com"],
+    ["mingyueming-click", "Mailmomy (mingyueming.click)", "mailmomy.com"],
+    ["mingyueming-shop", "Mailmomy (mingyueming.shop)", "mailmomy.com"],
+    ["mingyukeji-lol", "Mailmomy (mingyukeji.lol)", "mailmomy.com"],
+    ["mn-curppa-com", "Mailinator (mn.curppa.com)", "mailinator.com"],
+    ["m-nik-me", "Mailinator (m.nik.me)", "mailinator.com"],
+    ["mtmdev-com", "Mailinator (mtmdev.com)", "mailinator.com"],
+    ["nospam-thurstons-us", "Mailinator (nospam.thurstons.us)", "mailinator.com"],
+    ["notfond-404-mn", "Mailinator (notfond.404.mn)", "mailinator.com"],
+    ["null-k3vin-net", "Mailinator (null.k3vin.net)", "mailinator.com"],
+    ["nuxh62-space", "Mailmomy (nuxh62.space)", "mailmomy.com"],
+    ["proid-cloud-ip-cc", "Mailmomy (proid.cloud-ip.cc)", "mailmomy.com"],
+    ["ramjane-mooo-com", "Mailinator (ramjane.mooo.com)", "mailinator.com"],
+    ["rauxa-seny-cat", "Mailinator (rauxa.seny.cat)", "mailinator.com"],
+    ["really-istrash-com", "Mailinator (really.istrash.com)", "mailinator.com"],
+    ["sbook-pics", "Mailmomy (sbook.pics)", "mailmomy.com"],
+    ["spam-hortuk-ovh", "Mailinator (spam.hortuk.ovh)", "mailinator.com"],
+    ["sp-woot-at", "Mailinator (sp.woot.at)", "mailinator.com"],
+    ["test-unergie-com", "Mailinator (test.unergie.com)", "mailinator.com"],
+    ["torch-yi-org", "Mailinator (torch.yi.org)", "mailinator.com"],
+    ["t-zibet-net", "Mailinator (t.zibet.net)", "mailinator.com"],
+    ["xue32-buzz", "Mailmomy (xue32.buzz)", "mailmomy.com"],
+    ["apihz", "ApiHz TempMail", "apihz.cn"],
+    ["sogetthis-com", "Mailinator (sogetthis.com)", "mailinator.com"],
+    ["bobmail-info", "Mailinator (bobmail.info)", "mailinator.com"],
+    ["suremail-info", "Mailinator (suremail.info)", "mailinator.com"],
+    ["binkmail-com", "Mailinator (binkmail.com)", "mailinator.com"],
+    ["veryrealemail-com", "Mailinator (veryrealemail.com)", "mailinator.com"],
+    ["mailmomy", "Mailmomy", "mailmomy.com"],
+    ["chammy-info", "Mailinator (chammy.info)", "mailinator.com"],
+    ["thisisnotmyrealemail-com", "Mailinator (thisisnotmyrealemail.com)", "mailinator.com"],
+    ["notmailinator-com", "Mailinator (notmailinator.com)", "mailinator.com"],
+    ["spamhereplease-com", "Mailinator (spamhereplease.com)", "mailinator.com"],
+    ["sendspamhere-com", "Mailinator (sendspamhere.com)", "mailinator.com"],
+    ["sendfree-org", "Mailinator (sendfree.org)", "mailinator.com"],
+    ["junk-beats-org", "Mailinator (junk.beats.org)", "mailinator.com"],
+    ["junk-ihmehl-com", "Mailinator (junk.ihmehl.com)", "mailinator.com"],
+    ["junk-noplay-org", "Mailinator (junk.noplay.org)", "mailinator.com"],
+    ["junk-vanillasystem-com", "Mailinator (junk.vanillasystem.com)", "mailinator.com"],
+    ["spam-jasonpearce-com", "Mailinator (spam.jasonpearce.com)", "mailinator.com"],
+    ["fish-skytale-net", "Mailinator (fish.skytale.net)", "mailinator.com"],
+    ["spam-mccrew-com", "Mailinator (spam.mccrew.com)", "mailinator.com"],
+    ["dropmail-click", "DropMail.click", "dropmail.click"],
+    ["spam-coroiu-com", "Mailinator (spam.coroiu.com)", "mailinator.com"],
+    ["spam-deluser-net", "Mailinator (spam.deluser.net)", "mailinator.com"],
+    ["spam-dhsf-net", "Mailinator (spam.dhsf.net)", "mailinator.com"],
+    ["spam-lucatnt-com", "Mailinator (spam.lucatnt.com)", "mailinator.com"],
+    ["spam-lyceum-life-com-ru", "Mailinator (spam.lyceum-life.com.ru)", "mailinator.com"],
+    ["spam-netpirates-net", "Mailinator (spam.netpirates.net)", "mailinator.com"],
+    ["spam-no-ip-net", "Mailinator (spam.no-ip.net)", "mailinator.com"],
+    ["spam-ozh-org", "Mailinator (spam.ozh.org)", "mailinator.com"],
+    ["spam-pyphus-org", "Mailinator (spam.pyphus.org)", "mailinator.com"],
+    ["spam-shep-pw", "Mailinator (spam.shep.pw)", "mailinator.com"],
+    ["spam-wtf-at", "Mailinator (spam.wtf.at)", "mailinator.com"],
+    ["spam-wulczer-org", "Mailinator (spam.wulczer.org)", "mailinator.com"],
+    ["crap-kakadua-net", "Mailinator (crap.kakadua.net)", "mailinator.com"],
+    ["spam-janlugt-nl", "Mailinator (spam.janlugt.nl)", "mailinator.com"],
+    ["min-burningfish-net", "Mailinator (min.burningfish.net)", "mailinator.com"],
+    ["sink-fblay-com", "Mailinator (sink.fblay.com)", "mailinator.com"],
+    ["tempgmailer", "TempGmailer", "tempgmailer.com"],
+    ["temp-mail-org", "Temp-Mail.org", "temp-mail.org"],
+    ["xkx-me", "XKX.me", "xkx.me"],
+    ["gonebox-email", "Gonebox Email", "gonebox.email"],
+    ["mailcat-ai", "Mailcat AI", "mailcat.ai"],
+    ["tempgo-email", "TempGo Email", "tempgo.email"],
+    ["restmail-net", "Restmail.net", "restmail.net"],
+    ["dropmail-me", "DropMail.me", "dropmail.me"],
+    ["ten-minute-mail-net", "10MinuteMail.net", "10minutemail.net"],
+  ].freeze
+end

data/lib/tempmail_sdk/client.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  # SDK 主入口：聚合所有渠道逻辑，提供统一的无状态 API 与有状态 Client
+  module Client
+    module_function
+
+    # 所有支持的公共渠道标识（有序），由注册表派生
+    def all_channels
+      Registry::REGISTRY.map(&:channel)
+    end
+
+    # 渠道信息映射表，由注册表派生
+    def channel_info_map
+      @channel_info_map ||= Registry::REGISTRY.each_with_object({}) do |spec, h|
+        h[spec.channel] = ChannelInfo.new(channel: spec.channel, name: spec.name, website: spec.website)
+      end
+    end
+
+    # 获取所有支持的渠道列表（有序，与 baseline 逐行一致）
+    # @return [Array<ChannelInfo>]
+    def list_channels
+      map = channel_info_map
+      all_channels.map { |ch| map[ch] }
+    end
+
+    # 获取指定渠道的详细信息
+    # @param channel [String]
+    # @return [ChannelInfo, nil]
+    def channel_info(channel)
+      channel_info_map[channel]
+    end
+
+    # 创建临时邮箱
+    #
+    # 错误处理策略：
+    # - 指定渠道失败时，自动尝试其他可用渠道（打乱顺序逐个尝试）
+    # - 未指定渠道时，打乱全部渠道逐个尝试，直到成功
+    # - 所有渠道均不可用时返回 nil（不抛出异常）
+    #
+    # @param options [GenerateEmailOptions, nil]
+    # @return [EmailInfo, nil]
+    def generate_email(options = nil)
+      options ||= GenerateEmailOptions.new
+      logger = Log.logger
+      try_order = build_channel_order(options.channel)
+
+      max_channels = options.max_channels_tried.to_i.positive? ? options.max_channels_tried : 20
+      total_timeout = options.total_timeout.to_f.positive? ? options.total_timeout : 60.0
+      start_time = Time.now
+      channels_tried = 0
+      last_err = ""
+
+      try_order.each do |ch|
+        if channels_tried >= max_channels
+          logger.warn("已尝试最大渠道数 (#{max_channels})，停止")
+          break
+        end
+        if Time.now - start_time >= total_timeout
+          logger.warn("整体超时，停止尝试")
+          break
+        end
+
+        channels_tried += 1
+        logger.info("创建临时邮箱, 渠道: #{ch}")
+        r = Retry.with_retry_with_attempts(options.retry_config) { generate_email_once(ch, options) }
+        if r.ok?
+          result = r.value
+          logger.info("邮箱创建成功: #{result.email} (渠道: #{ch})")
+          Telemetry.report(operation: "generate_email", channel: ch, success: true,
+                           attempt_count: r.attempts, channels_tried: channels_tried, error: "")
+          return result
+        end
+
+        last_err = r.error ? r.error.message.to_s : "unknown"
+        logger.warn("渠道 #{ch} 不可用: #{last_err}，尝试下一个渠道")
+      end
+
+      logger.error("所有渠道均不可用，创建邮箱失败")
+      Telemetry.report(operation: "generate_email", channel: "", success: false,
+                       attempt_count: 0, channels_tried: channels_tried, error: last_err)
+      nil
+    end
+
+    # 构建渠道尝试顺序：指定渠道优先，其余打乱追加；未指定则全部打乱
+    # 返回值为本端运行时随机顺序，不作为跨 SDK 一致性约束
+    def build_channel_order(preferred = nil)
+      shuffled = all_channels.shuffle
+      return shuffled unless preferred
+
+      [preferred] + shuffled.reject { |ch| ch == preferred }
+    end
+
+    # 单次创建邮箱（不含重试逻辑）
+    def generate_email_once(channel, options)
+      spec = Registry::REGISTRY_MAP[channel]
+      raise "Unknown channel: #{channel}" if spec.nil?
+
+      spec.generate.call(options)
+    end
+
+    # 获取邮件列表
+    # Channel/Email/Token 等由 SDK 从 EmailInfo 中自动获取，用户无需手动传递
+    #
+    # @param info [EmailInfo]
+    # @param options [GetEmailsOptions, nil]
+    # @return [GetEmailsResult]
+    def get_emails(info, options = nil)
+      if info.nil?
+        Telemetry.report(operation: "get_emails", channel: "", success: false, attempt_count: 0,
+                         channels_tried: 0, error: "EmailInfo is required, call generate_email() first")
+        raise ArgumentError, "EmailInfo is required, call generate_email() first"
+      end
+
+      channel = info.channel
+      email = info.email
+      token = info.token
+      retry_config = options&.retry_config
+      logger = Log.logger
+
+      if channel.nil? || channel.empty?
+        Telemetry.report(operation: "get_emails", channel: "", success: false, attempt_count: 0,
+                         channels_tried: 0, error: "channel is required")
+        raise ArgumentError, "channel is required"
+      end
+      if (email.nil? || email.empty?) && channel != "tempmail-lol"
+        Telemetry.report(operation: "get_emails", channel: channel, success: false, attempt_count: 0,
+                         channels_tried: 0, error: "email is required")
+        raise ArgumentError, "email is required"
+      end
+
+      logger.debug("获取邮件, 渠道: #{channel}, 邮箱: #{email}")
+      r = Retry.with_retry_with_attempts(retry_config) { get_emails_once(channel, email, token) }
+
+      if r.ok?
+        emails = r.value
+        if emails.empty?
+          logger.debug("暂无邮件, 渠道: #{channel}")
+        else
+          logger.info("获取到 #{emails.size} 封邮件, 渠道: #{channel}")
+        end
+        Telemetry.report(operation: "get_emails", channel: channel, success: true,
+                         attempt_count: r.attempts, channels_tried: 0, error: "")
+        return GetEmailsResult.new(channel: channel, email: email, emails: emails, success: true)
+      end
+
+      err_s = r.error ? r.error.message.to_s : "unknown"
+      logger.error("获取邮件失败, 渠道: #{channel}, 错误: #{err_s}")
+      Telemetry.report(operation: "get_emails", channel: channel, success: false,
+                       attempt_count: r.attempts, channels_tried: 0, error: err_s)
+      GetEmailsResult.new(channel: channel, email: email, emails: [], success: false)
+    end
+
+    # 单次获取邮件（不含重试逻辑）
+    def get_emails_once(channel, email, token)
+      spec = Registry::REGISTRY_MAP[channel]
+      raise "Unknown channel: #{channel}" if spec.nil?
+
+      spec.get_emails.call(email, token)
+    end
+  end
+
+  # 临时邮箱客户端
+  # 封装邮箱创建和邮件获取的完整流程，自动管理邮箱信息和认证令牌
+  class TempEmailClient
+    def initialize
+      @email_info = nil
+    end
+
+    # 创建临时邮箱并缓存邮箱信息
+    # @param options [GenerateEmailOptions, nil]
+    # @return [EmailInfo, nil]
+    def generate(options = nil)
+      @email_info = Client.generate_email(options)
+    end
+
+    # 获取当前邮箱的邮件列表，必须先调用 generate
+    # @param options [GetEmailsOptions, nil]
+    # @return [GetEmailsResult]
+    def get_emails(options = nil)
+      if @email_info.nil?
+        Telemetry.report(operation: "get_emails", channel: "", success: false, attempt_count: 0,
+                         channels_tried: 0, error: "No email generated. Call generate() first")
+        raise "No email generated. Call generate() first"
+      end
+      Client.get_emails(@email_info, options)
+    end
+
+    # 获取当前缓存的邮箱信息
+    # @return [EmailInfo, nil]
+    attr_reader :email_info
+  end
+end

data/lib/tempmail_sdk/config.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  # SDK 全局配置
+  # 包含代理、超时、SSL 等设置，作用于所有 HTTP 请求
+  #
+  # 支持环境变量自动读取（优先级低于代码设置）：
+  #   TEMPMAIL_PROXY    - 代理 URL
+  #   TEMPMAIL_TIMEOUT  - 超时秒数
+  #   TEMPMAIL_INSECURE - 设为 "1" 或 "true" 跳过 SSL 验证
+  #   DROPMAIL_AUTH_TOKEN / DROPMAIL_API_TOKEN - DropMail af_ 令牌（可选）
+  #   DROPMAIL_NO_AUTO_TOKEN - 禁止自动拉取/续期
+  #   DROPMAIL_RENEW_LIFETIME - renew 的 lifetime，默认 1d
+  #   APIHZ_ID / APIHZ_KEY - apihz（接口盒子）调用凭据（可选）
+  #   TEMPMAIL_TELEMETRY_ENABLED - true/false，默认 true；false/0/no 关闭匿名上报
+  #   TEMPMAIL_TELEMETRY_URL - 自定义上报端点
+  class SDKConfig
+    attr_accessor :proxy, :timeout, :insecure, :headers,
+                  :dropmail_auth_token, :dropmail_disable_auto_token, :dropmail_renew_lifetime,
+                  :apihz_id, :apihz_key, :telemetry_enabled, :telemetry_url
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(proxy: nil, timeout: 15, insecure: false, headers: nil,
+                   dropmail_auth_token: nil, dropmail_disable_auto_token: false,
+                   dropmail_renew_lifetime: nil, apihz_id: nil, apihz_key: nil,
+                   telemetry_enabled: nil, telemetry_url: nil)
+      @proxy = proxy                                       # 代理 URL，支持 http/https/socks5
+      @timeout = timeout                                   # 全局默认超时秒数
+      @insecure = insecure                                 # 跳过 SSL 证书验证（调试用）
+      @headers = headers                                   # 自定义请求头，合并到每个请求
+      @dropmail_auth_token = dropmail_auth_token           # DropMail af_ 令牌；空则自动申请
+      @dropmail_disable_auto_token = dropmail_disable_auto_token # true 时不自动 generate/renew
+      @dropmail_renew_lifetime = dropmail_renew_lifetime   # renew lifetime，默认 1d
+      @apihz_id = apihz_id                                 # apihz 调用 id；空则用公共账号
+      @apihz_key = apihz_key                               # apihz 调用 key；空则用公共账号
+      @telemetry_enabled = telemetry_enabled               # nil 默认开启；false 关闭
+      @telemetry_url = telemetry_url                       # 非空覆盖默认上报 URL
+    end
+    # rubocop:enable Metrics/ParameterLists
+  end
+
+  # 配置模块：全局配置读写与版本号（供 HTTP 客户端缓存失效判断）
+  module Config
+    module_function
+
+    # 从环境变量读取默认配置
+    # @return [SDKConfig]
+    def load_env_config
+      timeout_str = ENV.fetch("TEMPMAIL_TIMEOUT", nil)
+      timeout = timeout_str&.match?(/\A\d+\z/) ? timeout_str.to_i : 15
+      insecure = %w[1 true True TRUE].include?(ENV.fetch("TEMPMAIL_INSECURE", ""))
+      dm_tok = (ENV["DROPMAIL_AUTH_TOKEN"] || ENV["DROPMAIL_API_TOKEN"] || "").strip
+      dm_tok = nil if dm_tok.empty?
+      dm_no = %w[1 true yes].include?((ENV["DROPMAIL_NO_AUTO_TOKEN"] || "").strip.downcase)
+      dm_renew = (ENV["DROPMAIL_RENEW_LIFETIME"] || "").strip
+      dm_renew = nil if dm_renew.empty?
+
+      te_raw = (ENV["TEMPMAIL_TELEMETRY_ENABLED"] || "").strip.downcase
+      telemetry_enabled = nil
+      telemetry_enabled = false if %w[false 0 no].include?(te_raw)
+      telemetry_enabled = true if %w[true 1 yes].include?(te_raw)
+
+      tu = (ENV["TEMPMAIL_TELEMETRY_URL"] || "").strip
+      tu = nil if tu.empty?
+      apihz_id = (ENV["APIHZ_ID"] || "").strip
+      apihz_id = nil if apihz_id.empty?
+      apihz_key = (ENV["APIHZ_KEY"] || "").strip
+      apihz_key = nil if apihz_key.empty?
+      proxy = ENV.fetch("TEMPMAIL_PROXY", nil)
+      proxy = nil if proxy && proxy.empty?
+
+      SDKConfig.new(
+        proxy: proxy, timeout: timeout, insecure: insecure,
+        dropmail_auth_token: dm_tok, dropmail_disable_auto_token: dm_no,
+        dropmail_renew_lifetime: dm_renew, telemetry_enabled: telemetry_enabled,
+        telemetry_url: tu, apihz_id: apihz_id, apihz_key: apihz_key
+      )
+    end
+
+    @global_config = load_env_config
+    @config_version = 0
+
+    class << self
+      # 设置 SDK 全局配置
+      # 设置后自动使已缓存的 HTTP 客户端失效，下次请求按新配置重建
+      # @param config [SDKConfig, nil] 传入配置对象；为 nil 时用关键字参数构造
+      def set_config(config = nil, **kwargs)
+        @global_config = config || SDKConfig.new(**kwargs)
+        @config_version += 1
+        nil
+      end
+
+      # @return [SDKConfig] 当前全局配置
+      def get_config
+        @global_config
+      end
+
+      # @return [Integer] 当前配置版本号
+      def config_version
+        @config_version
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/html_utils.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  # HTML 文本提取辅助
+  module HtmlUtils
+    module_function
+
+    # 将 HTML 粗略转换为纯文本：剥离 script/style，去标签，压缩空白
+    # @param value [String, nil]
+    # @return [String]
+    def html_to_text(value)
+      return "" if value.nil? || value.empty?
+
+      s = value.gsub(%r{<script\b[^>]*>.*?</script>}mi, " ")
+      s = s.gsub(%r{<style\b[^>]*>.*?</style>}mi, " ")
+      s = s.gsub(/<[^>]+>/, " ")
+      s = unescape_entities(s)
+      s.split.join(" ")
+    end
+
+    # 转义 HTML 特殊字符
+    # @param text [String]
+    # @return [String]
+    def escape(text)
+      text.to_s
+          .gsub("&", "&amp;")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+          .gsub('"', "&quot;")
+    end
+
+    # 反转义常见 HTML 实体
+    def unescape_entities(text)
+      text.gsub("&amp;", "&")
+          .gsub("&lt;", "<")
+          .gsub("&gt;", ">")
+          .gsub("&quot;", '"')
+          .gsub("&#39;", "'")
+          .gsub("&nbsp;", " ")
+    end
+  end
+end