Warmbly文档
warmbly.com打开控制台

权限参考

Warmbly 提供的 22 项 API 权限的完整参考。

Warmbly 使用位掩码管理 API 权限。每项权限对应 uint64 中的一个位，因此单个整数即可表示以下权限的任意组合。

同一组权限转为小写后也用作 OAuth 权限范围：例如 READ_EMAILS 对应权限范围 read_emails。OAuth 访问令牌携带已授予权限的位掩码，并接受与 API 密钥完全相同的权限检查。

权限值

权限位值类别说明
READ_EMAILS01读取查看邮箱账户和设置
READ_CAMPAIGNS12读取查看营销活动和邮件序列
READ_CONTACTS24读取查看联系人列表、分群、备注和活动记录
READ_UNIBOX38读取访问统一收件箱
READ_ANALYTICS416读取查看分析数据和统计信息
WRITE_EMAILS532写入修改邮箱账户设置
WRITE_CAMPAIGNS664写入创建和修改营销活动及邮件序列
WRITE_CONTACTS7128写入创建和修改联系人、分群、备注及活动记录
WRITE_UNIBOX8256写入将邮件标记为已读或未读，并发送回复
BULK_CONTACTS9512批量操作批量导入、导出或删除联系人
BULK_CAMPAIGNS101024批量操作批量操作营销活动
REALTIME_SUBSCRIBE112048特殊权限订阅实时事件
WEBHOOKS124096特殊权限管理 Webhook 端点
API_KEYS138192特殊权限创建和管理 API 密钥
SEND_CAMPAIGNS1416384写入启动和停止营销活动（会实际发送邮件）
READ_TEMPLATES1532768读取查看回复模板
WRITE_TEMPLATES1665536写入创建和修改回复模板
READ_CRM17131072读取查看销售管道、商机和 CRM 任务
WRITE_CRM18262144写入创建和修改销售管道、商机及 CRM 任务
READ_AUDIT_LOGS19524288读取查看组织审计日志
INTEGRATIONS201048576特殊权限连接和管理第三方集成
WARMUP_ROUTING212097152特殊权限管理预热路由规则
AI_AGENT224194304特殊权限运行 AI 助手和 MCP 工具
AI_RESEARCH238388608特殊权限运行 AI 联系人调研

AI_AGENT 控制在 /v1/mcp 和 /ai/tools 上使用网页和操作手册工具（search_web、fetch_url、load_skill）的权限；其中其他工具各自检查所需的权限范围。API 密钥访问 AI 技能端点时，也受此权限约束；使用密钥创建、编辑或删除操作手册时，创建该密钥的成员还必须具有 manage_settings 权限。

SEND_CAMPAIGNS 与 WRITE_CAMPAIGNS 有意分开：编辑营销活动草稿与启动实际发送邮件的营销活动，所产生的影响范围不同，因此可以仅授予密钥前者权限。收件箱投递位置测试同样会从真实邮箱发送实际邮件，所以启动或取消测试，以及安排营销活动的投递位置监测，都需要 SEND_CAMPAIGNS；读取结果则需要 READ_ANALYTICS。

类别

读取

只读数据访问。适用于监控、报告和 BI 同步。

写入

允许修改资源，但不能启动营销活动。具有完整写入权限集的密钥可以编辑草稿，但无法开启营销活动。

批量操作

高容量操作。一次请求可能影响大量记录，因此这些权限独立于逐条记录的写入权限。

特殊权限

实时订阅、Webhook、集成、预热路由、AI 助手 / MCP 访问、AI 联系人调研，以及自助密钥管理。请按需逐项授予。

角色可以授予的权限

API 密钥或 OAuth 授权代表工作区中的某位成员执行操作，因此其权限始终不会超出该成员角色所覆盖的范围。每项 API 权限都映射到其所需的团队角色权限；工作区所有者具有全部权限。

API 权限成员所需权限
READ_EMAILS, READ_CAMPAIGNS, READ_TEMPLATESview_campaigns
READ_CONTACTS, READ_CRMview_contacts
READ_UNIBOX, WRITE_UNIBOXaccess_unibox
READ_ANALYTICS, READ_AUDIT_LOGSview_analytics
WRITE_EMAILSmanage_emails
WRITE_CAMPAIGNS, WRITE_TEMPLATES, BULK_CAMPAIGNSmanage_campaigns
WRITE_CONTACTS, WRITE_CRM, BULK_CONTACTSmanage_contacts
SEND_CAMPAIGNSsend_campaigns
WEBHOOKS, WARMUP_ROUTINGmanage_settings
API_KEYSmanage_api_keys
INTEGRATIONSuse_integrations
AI_AGENTuse_ai
AI_RESEARCHview_contacts 和 use_ai
REALTIME_SUBSCRIBE任意成员

适用情况：

  • 从控制台创建或编辑 API 密钥时，如果权限超出成员角色范围，将返回 403 api_key_permissions_exceed_caller 并拒绝操作。
  • 使用 API 密钥创建或编辑另一个 API 密钥时，结果必须处于调用方密钥的限制范围内：不能授予调用方密钥自身不具备的权限；如果调用方密钥仅允许访问部分邮箱或仅允许来自部分 IP 地址的请求，则新建或编辑后的密钥也必须限制为其子集。否则同样返回 403 api_key_permissions_exceed_caller。
  • OAuth 授权仅包含请求的权限范围中，批准授权的成员角色所覆盖的部分；每次请求都会根据该成员当前的角色重新检查。请参阅OAuth 权限范围。API_KEYS 永远不会授予 OAuth 应用，OAuth 令牌也不能创建、编辑、撤销或删除 API 密钥（403 oauth_token_not_allowed）。
  • 访问范围受限于选定资源的成员只能从其角色中获得 view_campaigns、view_analytics 和 access_unibox，因此代表该成员的密钥或授权也仅能具有这些权限所覆盖的读取权限，并仅能使用其访问范围允许的读取路由和授权（适用路由）。密钥自身的邮箱允许列表仍会叠加生效。访问范围受限的成员不能创建密钥。

预设组合

为方便使用，GET /api-keys/permissions 会返回两个预设。同一响应还包含 grantable，表示调用者可赋予密钥的权限掩码（其角色覆盖范围，或调用方密钥自身的权限），以及 app_scopes，表示 OAuth 应用可请求的权限掩码。

只读（688159）

所有读取权限的组合：

READ_EMAILS | READ_CAMPAIGNS | READ_CONTACTS | READ_UNIBOX | READ_ANALYTICS
  | READ_TEMPLATES | READ_CRM | READ_AUDIT_LOGS
= 1 | 2 | 4 | 8 | 16 | 32768 | 131072 | 524288
= 688159

完全访问（16777215）

全部 24 项权限：

(1 << 24) - 1 = 16777215

使用位掩码

组合权限

const READ_EMAILS = 1;
const READ_CAMPAIGNS = 2;
const SEND_CAMPAIGNS = 16384;

const permissions = READ_EMAILS | READ_CAMPAIGNS | SEND_CAMPAIGNS;
// 16387

检查权限

function hasPermission(permissions, required) {
  return (permissions & required) === required;
}

hasPermission(16387, 16384); // true: SEND_CAMPAIGNS granted
hasPermission(16387, 64);    // false: WRITE_CAMPAIGNS missing

拒绝未知权限位

如果请求的 permissions 字段包含已知权限集合之外的位，POST /api-keys 会拒绝该请求，防止旧客户端意外请求未来新增的权限。当前有效位掩码为 4194303。

常用权限集

监控集成

用于仪表板和报告：

const MONITORING =
  READ_EMAILS |     // 1
  READ_CAMPAIGNS |  // 2
  READ_ANALYTICS;   // 16
// 19

CRM 同步

const CRM_SYNC =
  READ_CONTACTS |   // 4
  WRITE_CONTACTS |  // 128
  BULK_CONTACTS |   // 512
  READ_CRM |        // 131072
  WRITE_CRM;        // 262144
// 393860

营销活动自动化（仅草稿，不发送）

const CAMPAIGN_DRAFTS =
  READ_CAMPAIGNS |    // 2
  WRITE_CAMPAIGNS |   // 64
  READ_CONTACTS |     // 4
  READ_TEMPLATES |    // 32768
  WRITE_TEMPLATES;    // 65536
// 98374

营销活动自动化（包含发送）

与上例相同，另加 SEND_CAMPAIGNS（16384）。只有集成确实需要启动营销活动时，才应授予此权限。

权限常量

export const Permissions = {
  READ_EMAILS: 1,
  READ_CAMPAIGNS: 2,
  READ_CONTACTS: 4,
  READ_UNIBOX: 8,
  READ_ANALYTICS: 16,
  WRITE_EMAILS: 32,
  WRITE_CAMPAIGNS: 64,
  WRITE_CONTACTS: 128,
  WRITE_UNIBOX: 256,
  BULK_CONTACTS: 512,
  BULK_CAMPAIGNS: 1024,
  REALTIME_SUBSCRIBE: 2048,
  WEBHOOKS: 4096,
  API_KEYS: 8192,
  SEND_CAMPAIGNS: 16384,
  READ_TEMPLATES: 32768,
  WRITE_TEMPLATES: 65536,
  READ_CRM: 131072,
  WRITE_CRM: 262144,
  READ_AUDIT_LOGS: 524288,
  INTEGRATIONS: 1048576,
  WARMUP_ROUTING: 2097152,
  AI_AGENT: 4194304,
  AI_RESEARCH: 8388608,
} as const;
class Permissions:
    READ_EMAILS = 1
    READ_CAMPAIGNS = 2
    READ_CONTACTS = 4
    READ_UNIBOX = 8
    READ_ANALYTICS = 16
    WRITE_EMAILS = 32
    WRITE_CAMPAIGNS = 64
    WRITE_CONTACTS = 128
    WRITE_UNIBOX = 256
    BULK_CONTACTS = 512
    BULK_CAMPAIGNS = 1024
    REALTIME_SUBSCRIBE = 2048
    WEBHOOKS = 4096
    API_KEYS = 8192
    SEND_CAMPAIGNS = 16384
    READ_TEMPLATES = 32768
    WRITE_TEMPLATES = 65536
    READ_CRM = 131072
    WRITE_CRM = 262144
    READ_AUDIT_LOGS = 524288
    INTEGRATIONS = 1048576
    WARMUP_ROUTING = 2097152
    AI_AGENT = 4194304
    AI_RESEARCH = 8388608
const (
    APIPermReadEmails        uint64 = 1 << iota // 1
    APIPermReadCampaigns                        // 2
    APIPermReadContacts                         // 4
    APIPermReadUnibox                           // 8
    APIPermReadAnalytics                        // 16
    APIPermWriteEmails                          // 32
    APIPermWriteCampaigns                       // 64
    APIPermWriteContacts                        // 128
    APIPermWriteUnibox                          // 256
    APIPermBulkContacts                         // 512
    APIPermBulkCampaigns                        // 1024
    APIPermRealtimeSubscribe                    // 2048
    APIPermWebhooks                             // 4096
    APIPermAPIKeys                              // 8192
    APIPermSendCampaigns                        // 16384
    APIPermReadTemplates                        // 32768
    APIPermWriteTemplates                       // 65536
    APIPermReadCRM                              // 131072
    APIPermWriteCRM                             // 262144
    APIPermReadAuditLogs                        // 524288
    APIPermIntegrations                         // 1048576
    APIPermWarmupRouting                        // 2097152
    APIPermAIAgent                              // 4194304
    APIPermAIResearch                           // 8388608
)

另请参阅

OAuth

通过授权码流程，允许第三方应用代表 Warmbly 工作区执行操作。

端点权限范围表

列出所有端点、各端点接受的身份验证类型，以及所需权限。

本页目录

权限值类别读取写入批量操作特殊权限角色可以授予的权限预设组合只读（688159）完全访问（16777215）使用位掩码组合权限检查权限拒绝未知权限位常用权限集监控集成CRM 同步营销活动自动化（仅草稿，不发送）营销活动自动化（包含发送）权限常量另请参阅