shopify-admin-email-deliverability-audit

用途

该技能用于扫描 Shopify 店铺的整个客户列表，标记出如果纳入营销邮件发送会损害可送达性的地址，包括：语法无效的地址、角色账号（info@、admin@、sales@ 等）、已知的一次性/临时域名，以及疑似硬退信模式。输出为一份可直接导入邮件平台的抑制列表。该技能为只读操作，不执行任何变更。

主要能力

对每个客户邮箱按顺序执行以下检测并赋予一个或多个标记：

invalid_syntax：未通过 RFC 5322 本地部分/域名校验、缺少 @、包含空白、连续点号、开头或结尾有点号
role_account：本地部分与 role_localparts 条目完全匹配（不区分大小写）
disposable_domain：域名匹配一次性域名列表（mailinator、guerrillamail、tempmail 类域名等）
plus_alias：本地部分包含 +（信息性标记，本身不是可送达性问题，但有助于去重）
bounce_suspect：启发式判断，如纯数字本地部分、长度超过 64 字符、全大写、重复字符（aaaaa）、键盘连续键（asdfghjk）
duplicate：同一规范化邮箱在客户集中已出现过

一个客户可携带多个标记；严重程度排序为 invalid_syntax > bounce_suspect > disposable_domain > role_account > plus_alias，据此决定推荐操作。

使用方式

前置条件：已认证的 Shopify CLI 会话，命令为 shopify store auth --store <domain> --scopes read_customers；API 权限范围为 read_customers。

参数：

store（字符串，必填）：店铺域名，例如 mystore.myshopify.com
marketing_consent_only（布尔，可选，默认 true）：仅扫描当前接受营销的客户，这些才是可能被发送邮件的风险对象
disposable_domains（数组，可选，默认内置列表）：覆盖内置的一次性域名列表
role_localparts（数组，可选，默认 ["info","admin","sales","support","contact","noreply","help","webmaster","postmaster"]）：标记为角色账号的本地部分前缀
format（字符串，可选，默认 human）：输出格式，human 或 json

工作流程：通过 customers 查询分页获取目标客户（first: 250，选择 id、defaultEmailAddress { emailAddress, marketingState }、numberOfOrders、tags、分页游标；若 marketing_consent_only 为 true，则过滤 query: "email_marketing_state:subscribed"），直到 hasNextPage: false；对每个邮箱运行检测规则并收集标记；按标记聚合计数，构建抑制列表。

使用的 GraphQL 查询（已针对 api_version 2025-01 验证）：

query DeliverabilityAudit($query: String, $after: String) {
  customers(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        displayName
        defaultEmailAddress {
          emailAddress
          marketingState
        }
        numberOfOrders
        amountSpent {
          amount
          currencyCode
        }
        tags
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

输出格式：CSV 文件 deliverability_audit_<YYYY-MM-DD>.csv，列包括 customer_id, email, flags, recommended_action, marketing_state, order_count, total_spent, created_at。recommended_action 取值为 suppress、review 或 keep。

适用场景

在每次大型促销发送前运行，高无效/退信率超过 2% 会危及发送域名声誉
将 role_account 标记视为软抑制：这些地址很少有意义地同意营销，且经常将邮件标记为垃圾邮件
即使客户列表静态，也建议每季度重新审计，因为域名声誉列表会变化，一次性邮箱提供商会新增域名
可与 marketing-consent-report 配合，确认同意状态与邮件服务提供商记录一致
将生成的抑制 CSV 交给邮件服务提供商的导入抑制列表功能；不要基于此审计静默删除 Shopify 中的客户

限制

只读技能，不执行任何变更，不发送邮件，不更改营销同意状态
无邮箱的客户（仅电话/POS 账户）会被跳过，不纳入抑制列表
内置一次性域名列表可能过时，新临时邮箱域名不在列表中，可通过 disposable_domains 参数覆盖
国际化邮箱地址的 Unicode 本地部分需通过 NFC 规范化；不要标记有效的 IDN 域名
遇到 THROTTLED（API 速率限制）时，等待 2 秒并最多重试 3 次

会话跟踪输出

技能在启动、每步之后和完成时输出固定格式的跟踪信息。启动时输出带边框的标题块，包含技能名、店铺域名和开始时间；每步之后输出 [N/TOTAL] 查询/变更、操作名、参数摘要和结果；完成时按 format 输出 human 或 json 格式的汇总。human 格式汇总包含扫描客户数、订阅客户数、各标记计数及百分比、推荐抑制数以及输出文件名。json 格式汇总包含 skill、store、customers_scanned、flags（各标记计数）、recommended_suppressions 和 output_file。

技能介绍

用途

主要能力

使用方式

适用场景

限制

会话跟踪输出