分析与审计

读取控制台、邮件送达能力、邮箱预热、营销活动、邮箱账户和用量分析数据，以及组织的审计记录。

分析端点提供与控制台相同的汇总数据：组织整体概览、邮件送达状况、预热进度、各营销活动表现（包括每日和每小时明细，以及并排比较）、邮箱健康状况和账户用量。审计端点返回组织的活动记录，即谁在何时、从哪里做了什么。所有端点均为只读。

所有分析路由共用一套身份验证要求：权限范围 READ_ANALYTICS · 组织权限 view_analytics。审计路由使用相同的组织权限，但有独立的 API 权限范围。权限范围参考见权限，凭据传入方式见身份验证。

除非另有说明，日期按 YYYY-MM-DD 解析。错误采用错误码中说明的标准 {error, message, code, request_id} 封装。

获取控制台分析数据

GET /analytics/dashboard

返回当前组织的主仪表板概览，包括汇总统计、近期活动、表现最佳的营销活动、邮箱健康状况和每日趋势序列。发送和互动总数只统计邮件步骤，已完成的等待和操作步骤不会使这些数字增加。邮箱健康分组互斥，并使用当前连接、同步或预热信誉状态中最严重的一项。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

参数	位置	类型	说明
`period`	query	string	取值为 `7d`、`30d`、`90d` 之一，按包含今天的 UTC 自然日计算。默认 `7d`；其他值均回退为 `7d`。
`campaign_ids`	query	string	可选。以逗号分隔营销活动 ID，或重复传入此参数，将营销活动相关部分限定到这些活动。最多 `100` 个。
`folder_ids`	query	string	可选。以逗号分隔营销活动文件夹 ID。每个文件夹表示请求时其中的所有营销活动。最多 `100` 个。

按营销活动或文件夹筛选

未提供 campaign_ids 和 folder_ids 时，仪表板覆盖工作区的所有营销活动。提供任一参数时，服务器会将它们解析为一个集合：明确指定的营销活动，加上当前位于指定文件夹中的所有营销活动。通过两种方式重复指定，或同时位于两个指定文件夹中的营销活动，只统计一次。

筛选会缩小所有基于营销活动发件计算的内容：overall_stats（发送、打开、点击、回复、退信、相应比率及 active_campaigns）、daily_trend、top_campaigns 和 recent_activity。它不会缩小描述工作区邮箱的 account_health、overall_stats.active_accounts 或 capacity_today，也不会影响不属于任何营销活动的直接发送邮件。

不属于当前组织或已不存在的 ID 会被丢弃，绝不会扩大筛选范围：如果指定项均不属于工作区，所有营销活动指标都为零。ID 格式错误，或任一类超过 100 个，返回 400。经过筛选的响应会在 scope 中回显本次计算范围：

{
  "scope": {
    "campaigns": [{ "id": "b1f2c3d4-0000-0000-0000-000000000001", "name": "Client A - Dentists" }],
    "folders": [{ "id": "f01d0000-0000-0000-0000-000000000004", "name": "Client A" }],
    "campaign_count": 6
  }
}

campaigns 和 folders 列出请求项中属于该工作区的部分；campaign_count 表示它们合计覆盖的不重复营销活动数。未筛选的请求不会返回 scope。

响应

{
  "period": "7d",
  "overall_stats": {
    "total_emails_sent": 1240,
    "total_opens": 612,
    "machine_opens": 88,
    "total_clicks": 143,
    "machine_clicks": 6,
    "total_replies": 57,
    "total_bounces": 9,
    "open_rate": 49.35,
    "click_rate": 11.53,
    "reply_rate": 4.6,
    "bounce_rate": 0.73,
    "active_campaigns": 4,
    "active_accounts": 12
  },
  "recent_activity": [
    {
      "type": "replied",
      "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
      "campaign_name": "Q2 outbound",
      "contact_email": "[email protected]",
      "contact_id": "c0ffee00-0000-0000-0000-000000000002",
      "timestamp": "2026-06-11T14:02:11Z",
      "sender_id": "5e11d0c4-0000-0000-0000-000000000003",
      "sender_email": "[email protected]"
    },
    {
      "type": "opened",
      "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
      "campaign_name": "Q2 outbound",
      "contact_email": "[email protected]",
      "contact_id": "c0ffee00-0000-0000-0000-000000000002",
      "timestamp": "2026-06-11T13:40:02Z",
      "origin": { "client": "Apple Mail", "client_type": "app", "device_type": "mobile", "os": "iOS", "country_code": "US", "city": "Austin" }
    }
  ],
  "top_campaigns": [
    {
      "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
      "name": "Q2 outbound",
      "status": "active",
      "emails_sent": 820,
      "open_rate": 51.2,
      "click_rate": 12.1,
      "reply_rate": 5.0
    }
  ],
  "account_health": {
    "total_accounts": 12,
    "healthy_accounts": 10,
    "warning_accounts": 1,
    "error_accounts": 1
  },
  "daily_trend": [
    { "date": "2026-06-05", "sent": 160, "opens": 79, "clicks": 18, "replies": 7 }
  ]
}

recent_activity 中的 opened 或 clicked 条目在记录到联系人对该步骤的首次打开或点击时，会带有 origin，其客户端、设备和位置对象与联系人时间线事件中的对象相同。

每个条目通过 sender_id 和 sender_email 标明该步骤的发件邮箱；如果存在发件身份别名，则使用别名。即使回复到达发件人 reply-to 指定的共享回复收件箱，也仍归因于该发件邮箱。

获取邮件送达能力看板

GET /analytics/deliverability

返回组织在指定时间窗口内的邮件送达状况：退信、垃圾邮件投诉、打开、点击和回复的数量及比率，禁止发送和死信积压情况，回复意图分布，种子邮箱投递位置（整体及按收件服务商划分），从预热推导出的各收件邮件托管服务商投递位置，整体健康等级及 0-100 综合评分（均基于文档所述阈值），每日时间序列，以及按邮箱和营销活动划分的明细。需要组织上下文。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

参数	位置	类型	说明
`from`	query	string	时间窗口起点，RFC 3339 时间戳。默认为七天前，采用 UTC。
`to`	query	string	时间窗口终点，RFC 3339 时间戳。默认为当前时间，采用 UTC。

响应

{
  "from": "2026-06-05T00:00:00Z",
  "to": "2026-06-12T00:00:00Z",
  "events_total": 1380,
  "bounce_count": 9,
  "complaint_count": 1,
  "unsubscribe_count": 4,
  "reply_count": 57,
  "open_count": 612,
  "click_count": 143,
  "suppressed_recipients": 21,
  "dlq_pending": 0,
  "intent_positive": 18,
  "intent_negative": 6,
  "intent_out_of_office": 11,
  "intent_question": 9,
  "intent_neutral": 13,
  "intent_automated": 22,
  "emails_sent": 1240,
  "bounce_rate": 0.73,
  "complaint_rate": 0.08,
  "open_rate": 49.35,
  "click_rate": 11.53,
  "reply_rate": 4.6,
  "spam_placement_rate": 6.5,
  "inbox_placement_rate": 93.5,
  "placement_samples": 40,
  "band": "healthy",
  "score": 91,
  "timeseries": [
    {
      "date": "2026-06-05",
      "sent": 160,
      "bounces": 1,
      "complaints": 0,
      "opens": 79,
      "clicks": 18,
      "replies": 7,
      "unsubscribes": 1
    }
  ],
  "by_mailbox": [
    {
      "email_account_id": "a0a1a2a3-0000-0000-0000-000000000003",
      "email": "[email protected]",
      "sent": 420,
      "bounces": 2,
      "complaints": 0,
      "bounce_rate": 0.48,
      "complaint_rate": 0.0,
      "band": "healthy"
    }
  ],
  "by_campaign": [
    {
      "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
      "name": "Q2 outbound",
      "sent": 820,
      "bounces": 5,
      "complaints": 1,
      "bounce_rate": 0.61,
      "complaint_rate": 0.12,
      "band": "watch"
    }
  ],
  "by_provider": [
    {
      "provider": "gmail",
      "label": "Gmail",
      "samples": 24,
      "inbox": 21,
      "promotions": 1,
      "spam": 1,
      "other": 0,
      "missing": 1,
      "inbox_rate": 87.5,
      "spam_rate": 4.17
    }
  ],
  "warmup_placement": [
    {
      "provider": "microsoft365",
      "label": "Microsoft 365",
      "delivered": 132,
      "spam": 6,
      "inbox_rate": 95.45,
      "spam_rate": 4.55
    }
  ]
}

intent_* 计数与 reply_count 是两种不同指标，彼此不构成汇总关系。reply_count 统计 reply 类型的邮件送达事件，即服务商或你自己的集成向记录事件接口报告的事件。intent_* 则统计 Warmbly 在已连接邮箱收到回复时进行分类的结果，每封回复计一次，也包含机器回复：休假通知归入 intent_out_of_office，自动回复、工单确认或退信通知归入 intent_automated。如果工作区没有上报回复事件，reply_count 会保持为零，但意图仍正常计数。

窗口内没有种子样本时，会省略 spam_placement_rate 和 inbox_placement_rate。种子样本指工作区投递位置测试中在该窗口内获得判定结果的测试邮件副本：inbox、promotions、other（其他 Gmail 分类标签页）、spam 或 missing（始终未到达）；发送失败或已取消的副本不计为样本。by_provider 按种子邮箱的服务商类别汇总同一批样本，其中 provider 为类别 ID（gmail、google_workspace、microsoft365、outlook、yahoo 等），label 为显示名称，比率为占 samples 的百分比。warmup_placement 提供按收件邮件托管服务商划分的持续预热信号，其中 provider 是托管服务商 ID（google_workspace、microsoft365、zoho、hostinger、other 等；无法检测托管服务商时，使用服务商分组 google、microsoft、yahoo 或 other），label 为显示名称，delivered 统计已验证到达的预热邮件，spam 为其中被收件服务商归入垃圾邮件的数量。预热收件人大多是其他工作区的邮箱，因此不会报告收件地址或域名。score 从 100 开始，分别扣除达到上限后不再增加的惩罚分：退信率最多扣 40 分，在 10% 时达到上限；投诉率最多扣 30 分，在 0.30% 时达到上限；垃圾邮件投递比例最多扣 40 分，在 40% 时达到上限。

获取邮箱预热分析数据

GET /analytics/warmup

返回日期范围内的预热发送和回复统计，包含摘要及每日序列。可选择限定为单个邮箱。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

结果限定在所选工作区，因此所有有权限的成员都会看到相同的邮箱历史。工作区整体结果将所有邮箱汇总为每日一行。average_daily 以活跃天数，即存在预热统计记录的日期数为分母。target_progress 为这些活跃日的总发送量除以计划目标总量；发送超过计划时可能大于 100。

total_received 和每日 emails_received 统计从预热池伙伴收到且已验证的预热邮件，按验证时所在的 UTC 日期分桶。某天有收件但没有预热计划时，该日发送量列为零，且不计入 days_active。

参数	位置	类型	说明
`from`	query	string	必填。范围起始日期（`YYYY-MM-DD`）。
`to`	query	string	必填。范围结束日期（`YYYY-MM-DD`）。
`email_id`	query	string (uuid)	可选。限定为一个邮箱账户。无效 UUID 会被忽略。

响应

{
  "email_account_id": "a0a1a2a3-0000-0000-0000-000000000003",
  "email": "",
  "date_range": {
    "from": "2026-06-01T00:00:00Z",
    "to": "2026-06-12T00:00:00Z"
  },
  "summary": {
    "total_sent": 210,
    "total_replied": 84,
    "total_received": 196,
    "average_daily": 17.5,
    "reply_rate": 40.0,
    "target_progress": 87.5,
    "days_active": 12
  },
  "daily_stats": [
    { "date": "2026-06-01", "emails_sent": 12, "emails_replied": 5, "emails_received": 11, "target_volume": 12 }
  ]
}

未提供 email_id 筛选时，email_account_id 为全零 UUID。

获取预热邮件投递位置

GET /analytics/warmup/placement

返回日期范围内，预热邮件在伙伴邮箱中的到达位置：主收件箱、Gmail 分类标签页（推广、动态、社交或论坛），或垃圾邮件。按 UTC 日期和收件服务商计数；工作区报告还按邮箱划分。需要组织上下文。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

所有数字均为实测，而非估算：只有收件邮箱自身的同步发现预热邮件并记录其到达文件夹后，才会计为一次投递。rescued 统计已要求收件邮箱移回收件箱的垃圾邮件投递；实际移动不会回传确认，因此该指标是请求挽救的数量，而非已验证的完成数量。unconfirmed 统计发送完成超过 24 小时、但尚无收件方报告发现的邮件，按发送日期分桶；服务商筛选无法拆分此项，因此仅在未筛选时报告。

rate 是控制台在每个邮箱旁显示的主要送达指标：inbox_rate 为最近 7 个 UTC 日中，到达收件箱或分类标签页的邮件占已投递邮件的比例；在投递样本达到 min_sample（20）之前，保持为 null。scope 始终为 major：该比率只统计 Google、Microsoft 和 Yahoo 收件方，因为这些服务商会依据发件人信誉筛选邮件。若邮箱的预热邮件只到达其他托管服务商，则没有该比率（delivered 为 0，band 为 none）。其他托管服务商始终包含在 summary、daily 和 providers 中，other_delivered 与 other_inbox_rate 表示它们在同一窗口内的对应指标；没有相关投递时分别为 0 和 null。band 在 90 及以上为 good，从 80 起为 fair，低于 80 为 poor，低于最低样本量为 collecting，没有投递为 none。每日 rolling_inbox_rate 是截至该日、同样三个服务商最近七天的比率；每日数量覆盖全部托管服务商，可按服务商筛选以查看单个服务商。比率为保留两位小数的百分比。

收件服务商分组为 google（Gmail 和 Google Workspace）、microsoft（Outlook.com 和 Microsoft 365）、yahoo（Yahoo 和 AOL）及 other；每组列出其 hosts，其中 host 为空表示尚未检测到收件方的邮件托管服务商。

参数	位置	类型	说明
`from`	query	string	可选。范围起始日期（`YYYY-MM-DD`）。默认为 `to` 前 29 天。
`to`	query	string	可选。范围结束日期（`YYYY-MM-DD`）。默认为今天，采用 UTC。
`email_id`	query	string (uuid)	可选。限定为工作区中的一个邮箱账户。省略则返回工作区报告，并额外包含 `mailboxes`。

范围超过 366 天、from 晚于 to、日期格式错误或 email_id 无效时，返回 400；email_id 不属于工作区时返回 404。

响应

{
  "email_account_id": "a0a1a2a3-0000-0000-0000-000000000003",
  "date_range": { "from": "2026-06-01T00:00:00Z", "to": "2026-06-30T00:00:00Z" },
  "summary": {
    "sent": 820, "delivered": 791, "inbox": 702, "tabs": 41, "spam": 48,
    "rescued": 44, "unconfirmed": 12, "inbox_rate": 93.93, "spam_rate": 6.07
  },
  "rate": {
    "window_days": 7, "min_sample": 20, "scope": "major", "delivered": 196, "inbox": 180, "tabs": 9, "spam": 7,
    "inbox_rate": 96.43, "band": "good"
  },
  "daily": [
    {
      "date": "2026-06-30",
      "sent": 30, "delivered": 29, "inbox": 27, "tabs": 1, "spam": 1, "rescued": 1, "unconfirmed": 0,
      "inbox_rate": 96.55, "spam_rate": 3.45, "rolling_inbox_rate": 96.43,
      "groups": [
        { "group": "google", "inbox": 15, "tabs": 1, "spam": 0, "rescued": 0 },
        { "group": "microsoft", "inbox": 12, "tabs": 0, "spam": 1, "rescued": 1 }
      ]
    }
  ],
  "providers": [
    {
      "group": "google",
      "sent": 0, "delivered": 402, "inbox": 351, "tabs": 41, "spam": 10, "rescued": 9, "unconfirmed": 0,
      "inbox_rate": 97.51, "spam_rate": 2.49,
      "hosts": [
        { "host": "google_workspace", "sent": 0, "delivered": 310, "inbox": 271, "tabs": 33, "spam": 6, "rescued": 6, "unconfirmed": 0, "inbox_rate": 98.06, "spam_rate": 1.94 },
        { "host": "gmail", "sent": 0, "delivered": 92, "inbox": 80, "tabs": 8, "spam": 4, "rescued": 3, "unconfirmed": 0, "inbox_rate": 95.65, "spam_rate": 4.35 }
      ]
    }
  ]
}

工作区报告，即未传入 email_id 的报告，会省略 email_account_id 并添加 mailboxes，范围内每个有活动的邮箱对应一行，先按 rate.inbox_rate 从低到高排列，再列出仍在收集样本的邮箱。每行包含窗口内的计数、自身的 rate 和 daily_inbox_rate；后者在范围内每天对应一个条目，无投递的日期为 null。

与预热数量历史一样，投递位置历史会在邮箱的整个生命周期内保留，并随工作区导出迁移。在此报告功能推出前记录的投递，以及实时计数遗漏的到达记录，会由后台任务根据仍保存的回执在数分钟内补计；这些记录只能区分收件箱或垃圾邮件，分类标签页和挽救数量均为 0。

获取营销活动分析数据

GET /analytics/campaigns/:id

返回单个营销活动的表现摘要，以及各邮件序列步骤的统计，可涵盖活动全部历史，或仅统计某个日期范围内发送的邮件。total_contacts 统计已加入活动的潜在客户，emails_pending 为这些潜在客户剩余计划执行的邮件步骤发送量。营销活动必须属于所选工作区。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

参数	位置	类型	说明
`id`	path	string (uuid)	营销活动 ID。
`from`	query	string	可选。统计时段首日（`YYYY-MM-DD`，UTC）。必须同时提供 `to`。
`to`	query	string	可选。统计时段末日（`YYYY-MM-DD`，UTC），包含当天。必须同时提供 `from`。

同时省略 from 和 to 时，统计营销活动全部历史。仅提供其中一个、日期采用其他格式，或 from 晚于 to，会返回 400，错误码为 bad_request。

统计时段按发送批次定义：选择 UTC 时间从 from 当日开始至 to 当日结束期间发出的邮件，并统计这些邮件产生的所有打开、点击、回复和退信，无论互动何时到达。9 月 5 日发送、9 月 10 日收到回复的邮件，会计入 9 月 1 日至 7 日的时段；8 月发送、9 月 3 日收到回复的邮件则不会计入。这样可确保各比率的分子和分母针对同一批邮件。时段影响 emails_sent、打开、点击、回复、正向回复和退信的数量及比率、interested_leads、reply_breakdown、steps 中的每行，以及 engagement 中的每个分桶；只要对应邮件在该时段发送，打开或点击就会计入。total_contacts 和 emails_pending 描述营销活动当前状态，不随统计时段变化。

date_range 表示指标覆盖的时段，以首日和末日的 UTC 零点表示：即传入的 from 和 to；统计全部历史时，则从营销活动首次发送日开始，尚未发送时从创建日开始，一直到今天。

响应

{
  "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
  "name": "Q2 outbound",
  "status": "active",
  "date_range": { "from": "2026-05-04T00:00:00Z", "to": "2026-06-12T00:00:00Z" },
  "summary": {
    "total_contacts": 500,
    "emails_sent": 820,
    "emails_pending": 60,
    "unique_opens": 410,
    "machine_opens": 52,
    "unique_clicks": 99,
    "machine_clicks": 4,
    "replies": 41,
    "positive_replies": 12,
    "interested_leads": 11,
    "bounces": 5,
    "unsubscribes": 3,
    "reply_breakdown": {
      "positive": 12,
      "neutral": 9,
      "negative": 14,
      "unsubscribe": 4,
      "unclassified": 2,
      "out_of_office": 17,
      "auto_reply": 6
    },
    "open_rate": 50.0,
    "click_rate": 12.07,
    "reply_rate": 5.0,
    "positive_reply_rate": 1.46,
    "bounce_rate": 0.61
  },
  "steps": [
    {
      "step_id": "5e9e0001-0000-0000-0000-000000000004",
      "name": "Intro",
      "position": 1,
      "emails_sent": 500,
      "opens": 260,
      "machine_opens": 31,
      "clicks": 61,
      "machine_clicks": 2,
      "replies": 28,
      "positive_replies": 8,
      "bounces": 3,
      "open_rate": 52.0,
      "click_rate": 12.2,
      "reply_rate": 5.6,
      "positive_reply_rate": 1.6,
      "bounce_rate": 0.6
    }
  ],
  "engagement": {
    "countries": [{ "key": "US", "opens": 120, "clicks": 31 }, { "key": "DE", "opens": 44, "clicks": 9 }],
    "clients": [{ "key": "Gmail", "opens": 98, "clicks": 20 }, { "key": "Outlook", "opens": 51, "clicks": 12 }],
    "devices": [{ "key": "desktop", "opens": 140, "clicks": 37 }, { "key": "mobile", "opens": 24, "clicks": 3 }],
    "surfaces": [{ "key": "hidden", "opens": 98, "clicks": 0 }, { "key": "desktop_app", "opens": 51, "clicks": 12 }, { "key": "mobile", "opens": 0, "clicks": 3 }]
  }
}

engagement 按国家或地区（ISO 代码）、邮件客户端、设备类型（desktop、mobile、tablet）和使用环境对营销活动的人工打开与点击分组，每个分桶统计不重复联系人。clients 的键可以是邮件客户端（Gmail、Apple Mail、Outlook）；若在浏览器打开且未识别客户端，则为 Webmail in <browser>；若是点击，则为链接打开时使用的浏览器。surfaces 结合设备与应用或网页邮箱，取值包括 mobile_app、desktop_app、tablet_app、webmail；两者均未知时仅使用设备类型，点击通常属于这种情况，除非请求由邮件应用自身发出；如果由邮箱服务商的图片代理获取邮件、无法判断设备，则为 hidden。每个列表只保留最活跃的八项；key 为空表示未知。识别国家或地区需要消费者进程安装 GeoLite2 数据库，否则所有相关行均为未知。

unique_opens、opens、total_opens 及所有打开率只统计人工打开。machine_opens 单独统计仅由自动抓取程序打开过的步骤，包括没有 UA 的客户端、已知扫描器网络，以及发生在实例自动打开判定窗口内的打开；该窗口从步骤分派到工作节点时开始。这些不计入打开数量。Apple Mail 隐私保护的中继（用户代理仅为 Mozilla/5.0），以及 Mac 上的 Mail 与新版 Windows Outlook 共用的简化 WebKit 特征，只有在该窗口内才被计为预取；它们本身不能证明是自动操作。对于曾被机器打开的步骤，之后若发生人工打开，会从 machine_opens 移入人工打开计数。machine_clicks 统计在某个步骤上只有自动点击的联系人，例如安全网关逐个访问链接；这些不计入只统计人工点击的 unique_clicks 或 total_clicks。

replies 统计人工回复，联系人每回复一个步骤计一次；外出通知和自动回复永远不计入。positive_replies 是其中被回复分类器判定为正向的子集；positive_reply_rate 是该数量占 emails_sent 的百分比，与 reply_rate 使用相同分母。interested_leads 统计至少有一次正向回复的不重复联系人，因此对两个步骤作出正向回复的潜在客户只计一次。步骤的分类以最新回复为准：先表示有兴趣、后来又回复拒绝的潜在客户，会计入 negative。

reply_breakdown 按分类拆分同一批回复。positive、neutral、negative、unsubscribe（要求停止联系的回复）和 unclassified（分类器无法归类，或在启用回复分类之前收到的回复）合计为 replies。out_of_office 和 auto_reply 统计自动应答，不属于人工回复，仅为完整呈现分类而列出。步骤和每日序列对正向回复采用相同计数方式，因此同一时段内可汇总到摘要。

steps 按邮件序列顺序列出营销活动的邮件步骤，与步骤列表返回的顺序一致。position 是步骤在这些邮件步骤中从 1 开始的序号，即画布以 Email N 显示的 N。它不是步骤自身的 position 字段：操作步骤不参与编号，删除步骤后不会留空号。应通过 step_id 将统计行对应到步骤。

steps 中每项都包含该步骤自身的比率：open_rate、click_rate、reply_rate、positive_reply_rate 和 bounce_rate 均以该步骤的 emails_sent 为分母，而不是以整个营销活动的发送量为分母，因此即使跟进步骤只触达十分之一的联系人，也能与首次联系作比较。步骤尚未发送任何邮件时，这些比率为 0。machine_opens 和 machine_clicks 遵循与摘要对应字段相同的规则，但范围限定为该步骤。

获取营销活动每日统计

GET /analytics/campaigns/:id/daily

返回单个营销活动在日期范围内每天的发送、打开、点击、回复和正向回复数量。营销活动必须属于调用者。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

参数	位置	类型	说明
`id`	path	string (uuid)	营销活动 ID。
`from`	query	string	必填。首日（`YYYY-MM-DD`，UTC）。
`to`	query	string	必填。末日（`YYYY-MM-DD`，UTC），包含当天。

每行表示至少有一次发送的 UTC 日期；该行的打开、点击、回复和正向回复均归属于当天发送的邮件，无论互动何时到达。某时段各行汇总后，与相同 from 和 to 的营销活动分析一致。

响应

序列通过 data 封装返回。

{
  "data": [
    { "date": "2026-06-05", "sent": 120, "opens": 61, "clicks": 14, "replies": 6, "positive_replies": 2 },
    { "date": "2026-06-06", "sent": 110, "opens": 58, "clicks": 12, "replies": 5, "positive_replies": 1 }
  ]
}

获取营销活动每小时统计

GET /analytics/campaigns/:id/hourly

返回单个营销活动在某一天的每小时统计。营销活动必须属于调用者。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

参数	位置	类型	说明
`id`	path	string (uuid)	营销活动 ID。
`date`	query	string	要报告的日期（`YYYY-MM-DD`，UTC）。默认为今天。

响应

序列通过 data 封装返回，并回显解析后的 date。每项的 hour 是 UTC 小时，范围 0 至 23，因此一天中的各行汇总后，与每日统计中该日的记录一致。

{
  "data": [
    { "hour": 9, "sent": 22, "opens": 11, "clicks": 3, "replies": 1 },
    { "hour": 10, "sent": 30, "opens": 16, "clicks": 4, "replies": 2 }
  ],
  "date": "2026-06-11"
}

比较营销活动

GET /analytics/campaigns/compare

返回日期范围内最多 10 个营销活动的并排表现比较。请求中的每个营销活动都必须属于调用者。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

参数	位置	类型	说明
`ids`	query	string	必填。逗号分隔的营销活动 UUID。无效条目会被丢弃，列表上限为 10 个。至少需要一个有效 ID。
`from`	query	string	必填。首日（`YYYY-MM-DD`，UTC）。
`to`	query	string	必填。末日（`YYYY-MM-DD`，UTC），包含当天。

每个营销活动的指标基于从 from 当日开始至 to 当日结束期间发送的邮件，以及这些邮件产生的所有打开、点击、回复和退信，与该时段营销活动分析使用同一发送批次。

响应

{
  "campaigns": [
    {
      "campaign_id": "b1f2c3d4-0000-0000-0000-000000000001",
      "name": "Q2 outbound",
      "status": "active",
      "emails_sent": 820,
      "open_rate": 50.0,
      "click_rate": 12.07,
      "reply_rate": 5.0,
      "bounce_rate": 0.61
    },
    {
      "campaign_id": "b1f2c3d4-0000-0000-0000-000000000005",
      "name": "Reactivation",
      "status": "paused",
      "emails_sent": 410,
      "open_rate": 44.1,
      "click_rate": 9.8,
      "reply_rate": 3.4,
      "bounce_rate": 1.2
    }
  ],
  "period": {
    "from": "2026-06-01T00:00:00Z",
    "to": "2026-06-12T00:00:00Z"
  }
}

列出邮箱状态

GET /analytics/accounts

返回所选工作区中邮箱账户的健康和用量状态，每次只返回有数量上限的一页。各邮箱读取会在页内批量执行，因此单页成本不会随全部邮箱数量增长。如果无法完成该页的用量读取，请求会失败，客户端不会收到未明确提示的不完整页面。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

查询参数

参数	位置	类型	说明
`email_ids`	query	string	逗号分隔的邮箱 UUID，最多 200 个，用于返回这些邮箱的状态。可用它仅请求当前页面显示的邮箱。其他工作区的 ID 不会匹配任何内容。无效或超限时返回 `400`。
`limit`	query	integer	遍历全部邮箱时的每页数量，范围 `1` 至 `1000`，默认 `1000`。无效值返回 `400`。设置 `email_ids` 时，该集合本身已有数量限制，因此实际上不再依赖此参数限制范围。
`cursor`	query	string	上一次响应 `pagination.next_cursor` 中的不透明键集游标。无效时返回 `400`。

响应

采用标准 data 加 pagination 封装返回。pagination.next_cursor 是下一页的不透明令牌，最后一页为 null。data 中每项的结构与获取邮箱状态相同。工作区邮箱数超过一页时，应沿 next_cursor 获取余下内容，超出部分不会被静默丢弃。

{
  "data": [
    {
      "id": "a0a1a2a3-0000-0000-0000-000000000003",
      "email": "[email protected]",
      "provider": "google",
      "status": "active",
      "last_synced_at": "2026-06-12T08:00:00Z",
      "health": { "status": "healthy", "score": 100, "issues": [] },
      "errors": [],
      "daily_usage": {
        "date": "2026-06-12",
        "campaign_sent": 18,
        "campaign_limit": 50,
        "warmup_sent": 22,
        "warmup_limit": 40
      },
      "in_campaign": true
    }
  ],
  "pagination": {
    "total": 1,
    "next_cursor": null,
    "has_more": false
  }
}

获取邮箱状态

GET /analytics/accounts/:id

返回单个邮箱账户的详细状态：综合健康评分（包含预热池信誉和实测预热投递位置）、当前错误、UTC 当日用量、预热状态、预热池健康情况，以及最近一段时间的预热收件箱到达率。账户必须属于所选工作区。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

参数	位置	类型	说明
`id`	path	string (uuid)	邮箱账户 ID。

响应

{
  "id": "a0a1a2a3-0000-0000-0000-000000000003",
  "email": "[email protected]",
  "provider": "google",
  "status": "active",
  "last_synced_at": "2026-06-12T08:00:00Z",
  "health": {
    "status": "warning",
    "score": 90,
    "issues": ["Warmup reputation needs watching"]
  },
  "errors": [
    {
      "id": "e1e1e1e1-0000-0000-0000-000000000006",
      "error_code": "IMAP_AUTH",
      "severity": "WARNING",
      "title": "Mailbox reconnect recommended",
      "message": "Token nearing expiry",
      "created_at": "2026-06-11T22:14:00Z"
    }
  ],
  "daily_usage": {
    "date": "2026-06-12",
    "campaign_sent": 18,
    "campaign_limit": 50,
    "warmup_sent": 22,
    "warmup_limit": 40
  },
  "warmup_status": {
    "enabled": true,
    "paused": false,
    "started_at": "2026-05-20T00:00:00Z",
    "current_volume": 22,
    "target_volume": 33,
    "max_volume": 40,
    "reply_rate": 35,
    "days_active": 23,
    "next_send_at": "2026-06-12T14:37:12Z"
  },
  "warmup_health": {
    "state": "watch",
    "score": 78,
    "spam_score": 0,
    "partner_mailboxes_7d": 14,
    "partner_domains_7d": 11,
    "partner_organizations_7d": 9,
    "received_7d": 12,
    "senders_7d": 8,
    "evaluated_at": "2026-06-12T06:00:00Z"
  },
  "warmup_placement": {
    "window_days": 7,
    "min_sample": 20,
    "scope": "major",
    "delivered": 142,
    "inbox": 126,
    "tabs": 5,
    "spam": 11,
    "inbox_rate": 92.25,
    "band": "good"
  },
  "in_campaign": true
}

仅在发送安全限制暂停邮箱发送时出现 send_recovery_reason，取值为 authentication（重新连接邮箱可清除）、permanent、conflict 或 unknown。只有曾启用预热时才会出现 warmup_status；其 next_send_at 是邮箱下一次已排队预热发送的计划时间，没有排队任务时省略，例如预热暂停期间。只有邮箱处于预热池中时才出现 warmup_health。in_campaign 表示邮箱当前是否为正在运行的营销活动提供发送支持。

warmup_placement 是邮箱最近 7 个 UTC 日的实测预热收件箱到达率，与获取预热邮件投递位置返回的 rate 相同；该窗口没有任何投递时省略。一旦有 inbox_rate，health.score 就不能超过该值，向下取整，因此只要邮箱有邮件落入垃圾邮件，评分就不会再显示为 100；低于 90 时，还会将 health.status 至少设为 warning，并附上说明该比率的问题。

daily_usage.warmup_sent 和 campaign_sent 都统计邮箱当天实际完成的发送量，这也是强制执行发送上限所依据的值，因此两者都不会超过当前生效的目标。

三个 partner_*_7d 计数表示最近七天内，通过已确认预热发送触达的不重复伙伴：邮箱、其域名及其所属工作区。失败或仍待完成的尝试不计入。如果整周 partner_organizations_7d 都为 1，表示邮箱只在一个工作区内部预热；对于未连接 Warmbly Cloud 的自托管实例，这是预期情况，其他环境则值得排查。

received_7d 和 senders_7d 表示同一窗口内的相反方向：已验证到达的预热邮件，以及这些邮件来自的不重复伙伴。只有邮箱自身同步验证的邮件才计入。如果邮箱在发送侧伙伴很多、接收侧很少，说明它收到的邮件少于发出的邮件；预热池会在每次选择收件方时优先考虑它，直到两侧趋于均衡。

获取用量概览

GET /analytics/usage

返回所选工作区的邮箱账户、营销活动和联系人用量计数。campaigns.emails_sent 统计请求时段内已发送的邮件步骤，不计入等待和操作步骤。身份验证：权限范围 READ_ANALYTICS · 组织权限 view_analytics。

api 对象是兼容性占位符。如需真实的 API 密钥请求总数、错误率、延迟和端点明细，请使用 GET /api-keys/usage/summary 及 API 密钥分析端点。

参数	位置	类型	说明
`period`	query	string	`day` 从今天 UTC 00:00 开始统计，`week` 为滚动七天窗口，`month` 为滚动一个月窗口。默认 `day`；其他值回退为 `day`。

响应

{
  "user_id": "11111111-0000-0000-0000-000000000007",
  "period": "day",
  "email_accounts": { "total": 12, "active": 11, "in_warmup": 8, "with_errors": 1 },
  "campaigns": { "total": 9, "active": 4, "paused": 2, "draft": 3, "emails_sent": 124 },
  "contacts": { "total": 8200, "subscribed": 8050, "added_today": 120 },
  "api": { "total_calls": 0, "daily_limit": 50000, "top_endpoints": [] }
}

列出审计日志

GET /audit-logs

返回调用者当前组织的完整活动记录，即谁在何时、从哪里做了什么。组织始终从会话获取，不接受客户端参数指定，因此一个组织无法读取另一个组织的记录。身份验证：权限范围 READ_AUDIT_LOGS · 组织权限 view_analytics。

参数	位置	类型	说明
`limit`	query	int	每页数量。默认 `50`；必须在 `10` 至 `200` 之间，否则返回 `400`。
`cursor`	query	string (uuid)	来自 `pagination.next_cursor` 的不透明游标。无效游标返回 `400`。
`actor_id`	query	string (uuid)	限定为某个执行操作的成员。
`entity_id`	query	string (uuid)	限定为某个实体。
`entity_type`	query	string	按实体类型筛选，例如 `campaign`、`contact`、`email_account`、`api_key`、`webhook`。
`action`	query	string	按操作筛选，例如 `create`、`update`、`delete`、`send`、`revoke`。
`date`	query	string	按单日筛选（`YYYY-MM-DD`），扩展为该 UTC 日期的全天。
`start_date`	query	string	范围起点。RFC 3339 或 `YYYY-MM-DD`。覆盖 `date`。
`end_date`	query	string	范围终点。RFC 3339 或 `YYYY-MM-DD`。覆盖 `date`。

响应

data 加 pagination 响应封装，使用不透明游标。如果执行操作的用户之后已被删除，actor 为 null；entity_id、changes 和 metadata 为空时省略。

{
  "data": [
    {
      "id": "9c9c9c9c-0000-0000-0000-000000000008",
      "org_id": "0a0a0a0a-0000-0000-0000-000000000009",
      "user_id": "11111111-0000-0000-0000-000000000007",
      "actor": {
        "id": "11111111-0000-0000-0000-000000000007",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "[email protected]"
      },
      "action_date": "2026-06-12T08:14:00Z",
      "action": "update",
      "entity_type": "campaign",
      "entity_id": "b1f2c3d4-0000-0000-0000-000000000001",
      "ip_address": "203.0.113.10",
      "user_agent": "Mozilla/5.0",
      "changes": { "status": "paused" },
      "timestamp": "2026-06-12T08:14:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "c1_b3BhcXVlLWN1cnNvcg",
    "has_more": true
  }
}

机密值，包括 API 密钥内容、Webhook 密钥和密码，永远不会写入 changes 或 metadata；活动记录只说明某个字段发生了变更。

分析与审计

本页目录