收件箱投递位置测试

启动单次或批量投递位置测试，读取每封测试邮件的实际投递位置，管理工作区的种子测试邮箱，并安排营销活动的投递位置监控。

收件箱投递位置测试会从工作区中的一个邮箱，将模板或营销活动步骤发送到一组种子收件箱，并报告每封副本实际到达的位置：主收件箱、Gmail 分类标签页、垃圾邮件，或始终未到达。投递位置测试指南介绍测试邮件如何渲染、发送和查找，以及如何解读结果。

每条路由都限定在所选组织内，API 密钥始终绑定到一个组织；请求中的每个 ID 都会据此检查。发件邮箱、营销活动、步骤或联系人属于其他工作区时，返回 404。错误使用共享的 {error, message, code, request_id} 封装；这些路由新增的错误码列于投递位置测试拒绝原因。

测试开始、每次出现新的判定结果，以及测试完成或取消时，变更会以 PLACEMENT_TEST_UPDATED 事件实时推送到组织的实时通信通道。批次开始、跳过或延后某个邮箱，以及完成时，也会发送同一事件，以 batch_id 替代 test_id。

获取概览

GET /placement/overview

返回工作区可使用的种子邮箱组，包括各组的种子数量、服务商分布，以及工作区月度额度。

身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics

响应

{
  "data": {
    "panels": [
      {
        "panel": "instance",
        "available": true,
        "seeds": 38,
        "families": [
          { "family": "gmail", "label": "Gmail", "seeds": 10 },
          { "family": "google_workspace", "label": "Google Workspace", "seeds": 8 },
          { "family": "microsoft365", "label": "Microsoft 365", "seeds": 8 },
          { "family": "outlook", "label": "Outlook.com", "seeds": 6 },
          { "family": "yahoo", "label": "Yahoo Mail", "seeds": 6 }
        ],
        "metered": true
      },
      {
        "panel": "workspace",
        "available": false,
        "reason": "Mark one of this workspace's mailboxes as a seed inbox to test on it.",
        "seeds": 0,
        "families": [],
        "metered": false
      }
    ],
    "usage": {
      "used": 4,
      "limit": 40,
      "credits_per_test": 25,
      "credit_balance": 1840,
      "period_start": "2026-09-01T00:00:00Z",
      "period_end": "2026-10-01T00:00:00Z"
    },
    "workspace_seeds": 0,
    "seeds_per_test": 20,
    "spacing_seconds": 60
  }
}

字段	说明
`panels[].panel`	`instance`（运维人员维护的邮箱组）、`workspace`（工作区自己的种子收件箱）或 `cloud`（Warmbly Cloud 邮箱组）。自托管实例会列出 `cloud`，其他环境仅在可用时列出
`panels[].available`	当前能否在该邮箱组上运行测试。不能时，`reason` 用一句话说明原因
`panels[].families`	各服务商类别的种子数。`family` 是稳定 ID（`gmail`、`google_workspace`、`microsoft365`、`outlook`、`yahoo`、`aol`、`icloud`、`zoho`、`fastmail`、`gmx`、`proton`、`yandex`、`other` 等）；`label` 是显示名称
`panels[].metered`	在该邮箱组上测试是否计入月度额度
`usage`	当前 UTC 自然月已使用的免费测试数，相对于当月免费测试额度 `limit`。使用积分付费的测试，或结束时没有任何副本成功投递的测试，不计入此数。实例不计量测试时，`limit` 为 `null`；自托管实例始终如此
`usage.credits_per_test`	免费测试用尽后，在 `instance` 邮箱组运行一次测试所需的积分。无法付费测试时为 `0`，此时免费额度已用尽的工作区须等到下个月
`usage.credit_balance`	工作区可用积分；积分功能关闭时为 `null`
`seeds_per_test`	单次测试最多发送到多少个种子收件箱
`spacing_seconds`	同一发件邮箱发送两封测试副本之间的平均间隔

启动一次测试，或用于跟踪对比的两次关联测试。所有检查，包括功能资格、额度、进行中的测试数、发件邮箱状态和每日上限、可用种子，均在安排任何发送前完成，因此被拒绝的请求不会发送邮件，也不会扣费。付费测试启动时扣除积分，如果最终没有任何副本成功投递，会自动退款；insufficient_credits（402）或 usage_cap_exceeded（429）拒绝不会扣费。支持 Idempotency-Key，使用相同键重试绝不会重复扣费。

身份验证：权限范围 SEND_CAMPAIGNS · 组织权限 send_campaigns

请求体

字段	类型	必填	说明
`sender_account_id`	uuid	是	发送全部副本的邮箱。必须已连接且处于有效状态，不能是种子收件箱；如果 API 密钥有邮箱允许列表，还必须是密钥获准使用的邮箱
`campaign_id`	uuid	否	使用此营销活动的设置进行测试，包括退订说明、跟踪和附件
`sequence_id`	uuid	否	`campaign_id` 中的一个步骤。请求未提供主题和正文时，使用该步骤的内容。需要同时提供 `campaign_id`
`contact_id`	uuid	否	用于渲染联系人合并字段和 AI 内容块的联系人。默认使用营销活动的首位潜在客户；但在 `cloud` 邮箱组中，默认使用占位联系人，除非你明确选择联系人，否则不会让潜在客户详情离开实例。未使用联系人时省略 AI 内容块
`subject`	string	否	邮件主题。没有可读取主题的步骤时必填
`body_html`	string	否	HTML 正文。测试必须提供此字段或 `body_plain`
`body_plain`	string	否	纯文本正文
`tracking`	string	否	`campaign`（默认：采用营销活动自身的打开和点击跟踪设置，临时测试则不跟踪）、`on`、`off`，或 `compare`（向同一组种子分别运行不跟踪和启用跟踪的两次测试，每个种子在两次测试中收到相同的渲染内容）
`panel`	string	否	`instance`（默认）、`workspace` 或 `cloud`
`families`	string[]	否	仅使用这些服务商类别的种子，取值见 `panels[].families[].family`。适用于所有邮箱组；`instance` 和 `cloud` 的地址已脱敏，因此这是缩小测试范围的唯一方式。如果邮箱组中没有这些服务商的种子，会返回 `placement_no_seeds` 并拒绝测试
`pace`	string	否	`spaced`（默认，副本间隔约 60 秒）或 `quick`（约 8 秒，使测试在数分钟内发完）
`max_credits`	integer	否	当月 `instance` 邮箱组免费测试用尽后，你同意为此次测试支付的最高积分。价格超过此值，或未提供此字段的请求，会返回 `placement_quota_exceeded`，其 `message` 会说明价格，且不扣费。仍有免费测试时忽略此字段
`seed_ids`	uuid[]	否	仅适用于 `panel` 为 `workspace`：只向工作区中指定的种子收件箱发送。每个邮箱都必须是本工作区已连接且正在运行的种子收件箱，否则返回 `placement_invalid_seeds` 并列出不符合要求的邮箱。每个指定种子都会收到一封副本，`seeds_per_test` 不限制手动选择的列表。如果发件邮箱每日额度无法覆盖全部种子，则返回 `placement_daily_budget` 并拒绝请求，不会只发送其中一部分。与发件邮箱同域名的种子仍会照常跳过。省略时由测试自动选择

{
  "sender_account_id": "a0a1a2a3-0000-0000-0000-000000000003",
  "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
  "sequence_id": "c7d8e9f0-0000-0000-0000-000000000002",
  "tracking": "compare"
}

响应

201 Created，包含新测试：普通测试为一个；对比测试为两个，并共享 compare_group_id。副本将在数秒内开始发送。

{
  "data": [
    {
      "id": "d1e2f3a4-0000-0000-0000-000000000010",
      "sender_account_id": "a0a1a2a3-0000-0000-0000-000000000003",
      "sender_email": "[email protected]",
      "created_by": "9c2a0000-0000-0000-0000-000000000001",
      "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
      "sequence_id": "c7d8e9f0-0000-0000-0000-000000000002",
      "contact_id": "e5f6a7b8-0000-0000-0000-000000000004",
      "monitor_id": null,
      "subject": "Quick question about outbound at Acme",
      "open_tracking": false,
      "link_tracking": false,
      "compare_group_id": "f0f1f2f3-0000-0000-0000-000000000020",
      "origin": "manual",
      "panel": "instance",
      "status": "running",
      "pace": "spaced",
      "credits_charged": 0,
      "credits_refunded": 0,
      "credits_settled_at": null,
      "created_at": "2026-09-25T14:00:00Z",
      "finished_at": null,
      "summary": {
        "total": 38, "pending": 38, "inbox": 0, "promotions": 0, "other": 0, "spam": 0,
        "missing": 0, "failed": 0, "cancelled": 0, "delivered": 0,
        "inbox_rate": null, "tabs_rate": null, "spam_rate": null, "missing_rate": null
      },
      "families": []
    }
  ]
}

第二个元素在上例中省略，它是启用跟踪的一半，设置了 open_tracking 和 link_tracking。对比会占用两次测试额度和两个进行中测试名额，并发送两倍数量的副本。

列出测试

GET /placement/tests

返回工作区的测试，按最新优先排序，每项包含统计数量。列表省略副本正文。

身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics

参数	位置	类型	说明
`limit`	query	integer	`1` 至 `100`，默认 `25`。其他值返回 `400`
`cursor`	query	string	来自此前 `pagination.next_cursor` 的不透明游标。不是由本 API 签发的游标会返回 `400`
`campaign_id`	query	uuid	仅返回此营销活动的测试

列表不包含由批次启动的测试；请通过所属批次读取。

响应

{
  "data": [
    {
      "id": "d1e2f3a4-0000-0000-0000-000000000010",
      "sender_email": "[email protected]",
      "status": "completed",
      "panel": "instance",
      "origin": "manual",
      "finished_at": "2026-09-25T16:20:00Z",
      "summary": {
        "total": 38, "pending": 0, "inbox": 27, "promotions": 4, "other": 1, "spam": 4,
        "missing": 2, "failed": 0, "cancelled": 0, "delivered": 38,
        "inbox_rate": 0.7105, "tabs_rate": 0.1316, "spam_rate": 0.1053, "missing_rate": 0.0526
      },
      "families": [
        {
          "family": "gmail",
          "label": "Gmail",
          "counts": {
            "total": 10, "pending": 0, "inbox": 5, "promotions": 4, "other": 1, "spam": 0,
            "missing": 0, "failed": 0, "cancelled": 0, "delivered": 10,
            "inbox_rate": 0.5, "tabs_rate": 0.5, "spam_rate": 0, "missing_rate": 0
          }
        }
      ]
    }
  ],
  "pagination": { "total": 12, "has_more": false, "next_cursor": null }
}

每个测试都包含启动测试中展示的字段；示例作了精简。

字段	说明
`status`	`running`、`completed`、`cancelled` 或 `failed`。没有任何副本成功投递时，测试失败，原因见 `error`
`origin`	`manual`（由用户或密钥启动）、`monitor`（营销活动的投递位置监测）、`batch`（由 `batch_id` 指定的投递位置测试批次）、`admin`（运维人员）或 `remote`
`batch_id`	启动此测试的批次，其他情况为 `null`
`pace`	`spaced` 或 `quick`
`credits_charged`	当月免费测试用尽后，此测试消耗的积分；免费测试为 `0`
`credits_refunded`	付费测试未成功投递任何副本时退回的积分。如果扣费后月度积分额度已重置，原月度积分不会退回，因此可能小于 `credits_charged`
`credits_settled_at`	付费测试结束后完成结算的时间：没有投递则退款，否则保留扣费。免费测试或尚未结算时为 `null`
`summary`	全部副本的统计。`delivered` 等于 `inbox + promotions + other + spam + missing`，包含每封已离开发件邮箱且获得判定结果的副本
`summary.*_rate`	占 `delivered` 的比例，范围 `0` 至 `1`；尚无投递时为 `null`。`tabs_rate` 包含 `promotions` 和 `other`
`families`	按服务商类别划分的相同统计

获取测试

GET /placement/tests/:id

返回单个测试，包括测试内容、每个种子的结果、内容检查，以及跟踪对比时的另一半测试。

身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics

响应

{
  "data": {
    "id": "d1e2f3a4-0000-0000-0000-000000000010",
    "subject": "Quick question about outbound at Acme",
    "body_html": "<p>Hi Dana,</p><p>...</p>",
    "body_plain": "Hi Dana,\n\n...",
    "status": "completed",
    "panel": "instance",
    "summary": { "total": 38, "inbox": 27, "delivered": 38, "inbox_rate": 0.7105 },
    "families": [],
    "results": [
      {
        "seed": "a***@gmail.com",
        "family": "gmail",
        "family_label": "Gmail",
        "folder": "promotions",
        "scheduled_at": "2026-09-25T14:00:05Z",
        "sent_at": "2026-09-25T14:00:06Z",
        "detected_at": "2026-09-25T14:01:30Z"
      }
    ],
    "content": {
      "score": 84,
      "issues": []
    }
  }
}

测试自身字段与列出测试中相同，另加 body_html 和 body_plain；示例作了精简。

字段	说明
`results[].seed`	种子地址，在 `instance` 和 `cloud` 邮箱组中脱敏，在 `workspace` 中完整显示
`results[].folder`	`pending`、`inbox`、`promotions`、`other`（其他 Gmail 分类标签页：动态、社交或论坛）、`spam`、`missing`（`sent_at` 后 120 分钟内未发现）、`failed`（始终未离开发件邮箱，原因见 `error`）或 `cancelled`
`content`	测试内容的建议性评分，结构与为模板内容评分相同
`compare`	仅在跟踪对比中出现：另一半测试，包含计数，但不包含逐项结果

取消测试

POST /placement/tests/:id/cancel

停止尚未发送的副本。已发送的副本继续进行分类。支持 Idempotency-Key。

身份验证：权限范围 SEND_CAMPAIGNS · 组织权限 send_campaigns

响应

200 OK，包含与列表结构相同的测试。测试已经结束时，返回 409 和 placement_not_running。

启动批次

POST /placement/batches

从多个发件邮箱运行相同测试。首先整体验证请求，包括内容、邮箱组、跟踪、额度和同意支付的积分，然后解析并保存发件邮箱列表，立即返回状态为 queued 的批次。请求本身不会发送任何邮件：后端每次启动少量邮箱，各自运行独立测试，轮到该邮箱时再检查其每日上限、连接和工作节点。参阅批量测试发件邮箱。支持 Idempotency-Key。

身份验证：权限范围 SEND_CAMPAIGNS · 组织权限 send_campaigns

请求体

内容字段与启动测试相同：campaign_id、sequence_id、contact_id、subject、body_html、body_plain、tracking、panel、families 和 seed_ids。批次的 pace 始终为 spaced；使用 quick 返回 400。创建批次时只解析一次内容，因此每个发件邮箱测试的是同一封邮件。批次不使用 sender_account_id，而必须且只能提供以下两项之一：

字段	类型	说明
`sender_account_ids`	uuid[]	指定的这些邮箱。重复项会被去除；不属于工作区或属于种子收件箱的邮箱返回 `404`；API 密钥邮箱允许列表不允许使用的邮箱返回 `403`。已断开连接的邮箱仍会保留，轮到它时再延后或跳过
`sender_scope`	object	由服务端解析邮箱集合，因此数千个邮箱也无需提供 ID 列表
`sender_scope.type`	string	`campaign`（`campaign_id` 的调度器实际用于发送的所有邮箱），或 `workspace`（工作区的所有邮箱）
`sender_scope.campaign_id`	uuid	`type` 为 `campaign` 时必填
`sender_scope.providers`	string[]	仅选择由这些类别服务商托管的邮箱，例如 `google_workspace`、`gmail`、`microsoft365`、`outlook` 或 `other`
`sender_scope.domains`	string[]	仅选择使用这些域名发送的邮箱
`sender_scope.tag_ids`	uuid[]	仅选择带有这些标签之一的邮箱
`sender_scope.include_inactive`	boolean	保留已断开连接的邮箱。默认 `false`
`sender_scope.untested_days`	integer	仅选择最近指定天数内没有完成投递位置测试的邮箱，范围 `1` 至 `365` 天

字段	类型	必填	说明
`sample`	object	否	从解析出的邮箱中保留哪些。默认 `{"mode": "all"}`
`sample.mode`	string	否	`all`、`random`（选取 `count` 个邮箱）、`percent`（选取其中 `percent` 的比例，向上取整）、`per_domain` 或 `per_provider`（每组最多 `count` 个）
`sample.stratify`	string	否	仅适用于 `random` 或 `percent`：`provider` 或 `domain` 会按各组所占比例分配样本
`on_unavailable`	string	否	`defer`（默认：轮到邮箱时无法发送则重试，最长七天），或 `skip`
`max_credits`	integer	否	当月免费测试之外，你同意整个批次最多支付的积分。仅在批次所需测试数超过免费额度时需要；该值不足时，请求返回 `placement_quota_exceeded` 并说明最高可能费用。批次绝不会超出该金额

{
  "sender_scope": { "type": "campaign", "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001", "providers": ["google_workspace"] },
  "sample": { "mode": "percent", "percent": 10, "stratify": "domain" },
  "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
  "sequence_id": "c7d8e9f0-0000-0000-0000-000000000002",
  "tracking": "compare"
}

响应

201 Created，包含批次。

{
  "data": {
    "id": "a9b8c7d6-0000-0000-0000-000000000030",
    "created_by": "9c2a0000-0000-0000-0000-000000000001",
    "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
    "sequence_id": "c7d8e9f0-0000-0000-0000-000000000002",
    "contact_id": "e5f6a7b8-0000-0000-0000-000000000004",
    "subject": "Quick question about outbound at Acme",
    "tracking": "compare",
    "panel": "instance",
    "pace": "spaced",
    "families": [],
    "seed_ids": [],
    "on_unavailable": "defer",
    "selection": {
      "sender_scope": { "type": "campaign", "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001", "providers": ["google_workspace"] },
      "sample": { "mode": "percent", "percent": 10, "stratify": "domain" },
      "matched": 1126
    },
    "sender_count": 113,
    "max_credits": 0,
    "credits_spent": 0,
    "status": "queued",
    "retry_until": "2026-10-02T14:00:00Z",
    "created_at": "2026-09-25T14:00:00Z",
    "started_at": null,
    "finished_at": null,
    "progress": { "total": 113, "queued": 113, "deferred": 0, "running": 0, "completed": 0, "skipped": 0, "failed": 0, "cancelled": 0 },
    "summary": { "total": 0, "pending": 0, "inbox": 0, "promotions": 0, "other": 0, "spam": 0, "missing": 0, "failed": 0, "cancelled": 0, "delivered": 0, "inbox_rate": null, "tabs_rate": null, "spam_rate": null, "missing_rate": null }
  }
}

字段	说明
`status`	首个邮箱开始前为 `queued`，之后为 `running`；结束时为 `completed`、`completed_with_warnings`（部分邮箱被跳过或失败）、`failed`（没有邮箱完成测试，附带 `error`）或 `cancelled`
`selection`	邮箱选择方式，以及抽样前范围共 `matched` 多少个邮箱。具体邮箱为列出批次发件邮箱中的快照
`progress`	批次邮箱按状态的统计。`running` 表示测试尚未完成的邮箱
`summary`	批次副本截至目前的投递位置，统计营销活动实际发送的版本；对于跟踪对比，即启用跟踪的一半
`retry_until`	延后的邮箱会重试到此时间，之后跳过

预览批次

POST /placement/batches/preview

接受启动批次的请求体，返回预计结果，不写入或发送任何内容。可以省略内容字段，只统计邮箱；一旦提供任意内容字段，就会像启动批次一样检查内容。批次启动时会重新随机抽样，因此数量相同，但具体邮箱可能不同。

身份验证：权限范围 SEND_CAMPAIGNS · 组织权限 send_campaigns

响应

{
  "data": {
    "matched": 1347, "selected": 135, "inactive": 2, "domains": 41,
    "providers": [
      { "key": "google_workspace", "label": "Google Workspace", "senders": 80 },
      { "key": "other", "label": "Other provider", "senders": 40 },
      { "key": "microsoft365", "label": "Microsoft 365", "senders": 15 }
    ],
    "variants": 2, "tests": 270, "seeds_per_test": 20, "max_sends": 5400,
    "metered": true, "free_tests": 40, "paid_tests": 230, "credits": 5750,
    "usage": { "used": 0, "limit": 40, "credits_per_test": 25, "credit_balance": 9000, "period_start": "2026-09-01T00:00:00Z", "period_end": "2026-10-01T00:00:00Z" },
    "senders_max": 10000, "concurrency": 20
  }
}

字段	说明
`variants`	跟踪对比时为 `2`，会使 `tests` 和 `max_sends` 加倍
`max_sends`	批次最多发送的副本数：`tests` 乘以 `seeds_per_test`。各邮箱每日上限只会使实际数量更少
`free_tests`, `paid_tests`, `credits`	`tests` 如何分配到当月免费测试，以及付费部分的最高费用。不计量的邮箱组中均为 `0`
`concurrency`	工作区的批次邮箱中，同时发送的数量

列出批次

GET /placement/batches

按上述结构返回工作区的批次，最新优先。接受 limit（1 至 100，默认 25）和不透明的 cursor，返回 data 加 pagination。

身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics

获取批次

GET /placement/batches/:id

返回单个批次，以及在所有发件邮箱间分组汇总的投递位置。

身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics

响应

除上述批次字段外，还包含：

字段	说明
`untracked`	仅在跟踪对比中出现：未启用跟踪的一半的计数。`summary` 为启用跟踪的一半
`domains`	按发件域名分组，收件箱到达率最低的在前：`key`（域名）、批次中的 `senders`、`tested`（已完成测试的发件邮箱）和 `counts`
`providers`	按发件服务商划分的相同统计，`key` 为托管服务商类别，`label` 为其名称
`recipients`	按收件服务商类别的计数，与单个测试的 `families` 类似
`matrix`	按 `domains` 顺序列出各发件域名，并按 `recipients` 顺序列出其各收件服务商计数
`content`	批次内容的评分

各分组统计的内容版本与 summary 相同。不按工作节点划分：工作节点只负责登录邮箱服务商，实际投递由服务商自身的服务器完成，因此收件方过滤器看不到工作节点。

列出批次中的发件人

GET /placement/batches/:id/senders

返回批次中的邮箱，以及各邮箱测试副本的投递位置。

身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics

参数	位置	类型	说明
`limit`	query	integer	`1` 至 `100`，默认 `25`
`cursor`	query	string	此前 `pagination.next_cursor` 中的不透明游标
`sort`	query	string	`worst`（默认：收件箱到达率最低的在前，未测试的在最后）、`best`、`email` 或 `status`
`status`	query	string	仅返回此状态的邮箱：`queued`、`deferred`、`running`、`completed`、`skipped`、`failed` 或 `cancelled`
`q`	query	string	仅返回地址包含此文本的邮箱

响应

{
  "data": [
    {
      "id": "c0c1c2c3-0000-0000-0000-000000000040",
      "batch_id": "a9b8c7d6-0000-0000-0000-000000000030",
      "email_account_id": "a0a1a2a3-0000-0000-0000-000000000003",
      "sender_email": "[email protected]",
      "sender_domain": "domain2.com",
      "sender_family": "google_workspace",
      "sender_family_label": "Google Workspace",
      "status": "completed",
      "attempts": 1,
      "next_attempt_at": "2026-09-25T14:00:00Z",
      "started_at": "2026-09-25T14:02:00Z",
      "finished_at": "2026-09-25T16:40:00Z",
      "summary": { "total": 20, "pending": 0, "inbox": 8, "promotions": 0, "other": 0, "spam": 12, "missing": 0, "failed": 0, "cancelled": 0, "delivered": 20, "inbox_rate": 0.4, "tabs_rate": 0, "spam_rate": 0.6, "missing_rate": 0 },
      "test_ids": ["d1e2f3a4-0000-0000-0000-000000000011", "d1e2f3a4-0000-0000-0000-000000000012"]
    }
  ],
  "pagination": { "total": 113, "has_more": true, "next_cursor": "MjU" }
}

字段	说明
`status`	`queued`、`deferred`（等待在 `next_attempt_at` 重试）、`running`、`completed`、`skipped`、`failed` 或 `cancelled`
`reason`, `detail`	邮箱被延后、跳过或失败的原因：来自投递位置测试拒绝原因的错误码及其说明
`test_ids`	该邮箱的测试，可通过获取测试读取；对比时不跟踪的一半在前

取消批次

POST /placement/batches/:id/cancel

停止批次：不再启动任何邮箱，取消尚未发送的副本，已发送副本继续分类。

身份验证：权限范围 SEND_CAMPAIGNS · 组织权限 send_campaigns

响应

200 OK，包含批次。批次已经结束时返回 409 和 placement_batch_not_running。

获取发件邮箱的测试覆盖情况

GET /placement/coverage

工作区已连接的发件邮箱中，最近完成投递位置测试的数量。

身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics

响应

{
  "data": { "mailboxes": 1347, "tested_7d": 312, "tested_30d": 947, "never_tested": 126 }
}

列出种子测试邮箱

GET /placement/seeds

返回工作区的每个邮箱，以及它是否为工作区种子收件箱。仅允许访问特定邮箱的密钥只会看到这些邮箱。

身份验证：权限范围 READ_EMAILS · 组织权限 view_campaigns

响应

{
  "data": [
    {
      "email_account_id": "a0a1a2a3-0000-0000-0000-000000000009",
      "email": "[email protected]",
      "family": "gmail",
      "label": "Gmail",
      "status": "active",
      "seed": true
    },
    {
      "email_account_id": "a0a1a2a3-0000-0000-0000-000000000003",
      "email": "[email protected]",
      "family": "google_workspace",
      "label": "Google Workspace",
      "status": "active",
      "seed": false,
      "blocker": "A placement test is sending from this mailbox"
    }
  ]
}

邮箱当前无法成为种子收件箱时出现 blocker，并说明原因。

标记种子测试邮箱

PUT /placement/seeds/:email_account_id

将工作区邮箱设为种子收件箱，或恢复为普通邮箱。种子邮箱不会预热，此处会关闭预热，再次启动会返回 mailbox_is_seed 并拒绝；也不会发送营销活动邮件，不能作为投递位置测试的发件邮箱。请求体直接声明期望值，因此重试后会得到相同状态。

身份验证：权限范围 WRITE_EMAILS · 组织权限 manage_emails

请求体

字段	类型	必填	说明
`seed`	boolean	是	`true` 将邮箱设为种子收件箱，`false` 将其恢复为普通邮箱

{ "seed": true }

响应

200 OK，包含邮箱，结构与列出种子收件箱相同。属于实例邮箱组，或仍有测试正在从其发送的邮箱，会返回 409 和 placement_seed_unavailable；工作区已有 50 个种子收件箱时，返回 placement_seed_limit。

获取营销活动的投递位置监控

GET /campaigns/:id/placement-monitor

返回营销活动的计划投递位置测试；没有时返回 null。

身份验证：权限范围 READ_CAMPAIGNS · 组织权限 view_campaigns

响应

{
  "data": {
    "id": "a9b8c7d6-0000-0000-0000-000000000030",
    "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
    "created_by": "9c2a0000-0000-0000-0000-000000000001",
    "enabled": true,
    "interval_days": 7,
    "panel": "instance",
    "alert_below": 70,
    "pause_on_alert": false,
    "next_run_at": "2026-10-02T14:05:00Z",
    "last_run_at": "2026-09-25T14:05:00Z",
    "last_test_id": "d1e2f3a4-0000-0000-0000-000000000010",
    "last_alert_at": null,
    "created_at": "2026-09-18T14:00:00Z",
    "updated_at": "2026-09-25T14:05:00Z"
  }
}

上次运行无法启动测试时出现 last_error，并说明原因，例如营销活动未运行；监测器随后会在一天后重试。

设置营销活动的投递位置监控

PUT /campaigns/:id/placement-monitor

创建或更新营销活动监测器。所有字段均可选：省略字段保留当前值，新监测器则采用默认值。请求体声明期望值，而非增量变更，因此重试会得到相同状态。新建或重新启用的监测器会在约五分钟内运行首次测试；修改 interval_days 会将下次运行时间调整为上次运行后经过该间隔的时间。

每次运行都会测试营销活动中第一个同时具有主题和正文的邮件步骤，使用首位潜在客户渲染，采用活动自身的跟踪设置，并轮流使用营销活动发件邮箱中的下一个邮箱。仅在营销活动为 active 时运行，与其他测试一样计入测试额度和邮箱每日上限。

身份验证：权限范围 SEND_CAMPAIGNS · 组织权限 send_campaigns

请求体

字段	类型	默认值	说明
`enabled`	boolean	`true`	是否运行监测器
`interval_days`	integer	`7`	运行间隔天数，`1` 至 `30`
`panel`	string	`instance`	`instance`、`workspace` 或 `cloud`
`alert_below`	integer	`70`	收件箱百分比，`0` 至 `100`。某次运行的主收件箱占比低于该值时，会向所有有权查看营销活动的成员发送 `placement_alert` 通知
`pause_on_alert`	boolean	`false`	发出警报时同时暂停营销活动。活动转为 `paused_guardrail`，并在活动日志中记录原因；保持暂停，直到再次启动

{ "interval_days": 3, "alert_below": 80, "pause_on_alert": true }

响应

200 OK，包含上述结构的监测器。

移除营销活动的投递位置监控

DELETE /campaigns/:id/placement-monitor

移除营销活动监测器。已经运行的测试仍保留在列表中。

身份验证：权限范围 SEND_CAMPAIGNS · 组织权限 send_campaigns

响应

204 No Content。营销活动没有监测器时返回 404。

收件箱投递位置测试

本页目录