常见问题

本页汇总接入和排障中的高频问题。协议细节以对应指南为准，不再重复整份参数表。

开始前的准备

准备完整 Message ID、请求时间、HTTP 状态和响应 code；排查 Webhook 时还需 eventId。请勿在工单或日志中提交真实密钥。

接入与认证

在哪里获取 AppID 和 AppSecret？

在平台主框架 Console > Developers 查看和管理 API 凭证。AppID 对应完整 API Key；AppSecret 用于计算 CheckSum，也是 SMTP 密码。请仅在服务端保存，泄露时立即联系平台轮换。详见开始使用。

返回 401 或签名校验失败怎么办？

依次检查：

• AppID 与 API Secret 是否匹配且凭证仍启用；
• Nonce 是否为每次 HTTP 尝试新生成的随机值；
• CurTime 是否为当前 Unix 秒级时间戳，并与平台时间偏差在允许窗口内；
• CheckSum 是否为 SHA1(AppSecret + Nonce + CurTime) 的 40 位大写十六进制字符串；
• 是否同时误传了 Bearer 与签名参数，导致实际走了另一种认证方式；
• 出口 IP 是否满足该 API Key 的白名单。

认证错误码请以发送接口的 020001、020002、020008、020009 为准，详见发送 API 错误码。

同一任务重试要更换 Nonce 和幂等键吗？

使用 CheckSum 时，每次 HTTP 尝试都重新生成 Nonce、CurTime 和 CheckSum；但 X-Idempotency-Key 与请求体保持不变。幂等结果默认保留 24 小时，实际以接入环境为准，过期后不能依赖旧键防重。

发送与结果

API 返回成功，为什么收件人没收到？

成功只表示受理：HTTP 202 且 code=000000。之后还可能发生模板不可用、域名未授权、抑制、通道拒绝或退信。

请在发送记录按完整 Message ID 查询。已送达表示收件方服务器已接受，不代表一定进入收件箱；如未看到，请同时检查垃圾邮件文件夹和收件方策略。详见发送记录与状态。

批量中部分地址失败会影响整批吗？

分两个阶段：

1. 受理前：任一邮件对象触发请求或业务校验错误，整批拒绝，不受理任何子项。
2. 受理后：每封独立进入发送流程，最终可能出现不同结果。

事务邮件部分格式无效地址可能在 invalidRecipients 中给出预检查明细，但这不是最终失败清单。详见单封与批量发送。

群发活动提交后还能撤回吗？

提交审核不等于已经发送；尚未执行的待审核或已定时活动可按页面能力取消。进入发送流程后不能撤回。请先使用测试发送和小范围受众，再提交正式活动。详见控制台操作。

为什么批量不到 100 项仍然限流？

100 是单批子项上限，不是账号速率。批量按邮件对象数占用 API Key 的 TPS 窗口和日配额，余量不足会整批拒绝。日配额按 UTC 自然日切换，即 UTC 00:00（北京时间 08:00）。

域名与退订

域名添加后多久能验证或审核通过？

DNS 生效受 TTL 和缓存影响，人工审核还需要平台处理，没有统一的固定时长。请在详情页按实际记录配置并刷新。

等待域名验证完成；若详情页提示需要审核，请提交并等待平台处理。DMARC 建议记录可能是可选项，不要把“SPF、DKIM、DMARC 全部显示已验证”当作所有域名统一的提交前置条件。详见发信域名与身份验证。

删除抑制名单地址后，还会再次出现吗？

可能。后续硬退信等事件可能再次形成停止投递记录。删除前应先解决地址错误、投诉或对方拦截的根因，不要把删除名单当作绕过退订或投诉的方式。详见营销邮件与退订。

如何修改自动退订、Webhook 或配额？

这些属于 API Key 或租户级配置，需要联系平台运营。客户可以在退订页面设置修改退订页品牌和三语文案，但这不会开启 API Key 的自动退订开关，也不会修改 Webhook 或配额。

Webhook

配置了回调但收不到事件怎么办？

检查：

• 回调是否为公网可访问的 HTTPS 地址且证书有效；
• DNS 是否解析到被拒绝的内网或保留地址；
• 是否订阅了实际发生的事件类型；
• 接口是否在 10 秒内返回 2xx；
• 签名模式、时间戳单位、原始 Body 和签名编码是否正确；
• 打开和点击是否受当前通道追踪能力支持。

当前平台不自动重试，也不保证失败补发。请对照发送记录，并提供 Message ID 和 eventId 联系平台运营排查。详见事件推送 Webhook。

同一事件收到多次怎么办？

以正文 eventId 持久化去重，同一 Message ID 可以有多个不同事件类型。不要依赖旧的“CB- 与 CBRT- 成对出现”说明，也不要期待非 2xx 会触发自动重试。

其他能力

支持 SMTP、收信或邮件转发吗？

支持 SMTP 发送：控制台显示 smtp.innomails.com:587 + STARTTLS，用户名是 API Key，密码是 API Secret，没有独立 SMTP 密码。

当前不提供入站收信、IMAP/POP3 邮箱或邮件转发功能。IMAP 和 POP3 是收取已有邮箱邮件的协议，不是 邮件产品 的发送接入方式。

支持附件上传和实际附件投递吗？

当前没有可用的附件上传与内容存储能力。请求模型中即使存在附件引用字段，也不代表附件会随邮件投递，应省略 attachments。模板和正文能力见模板与变量。

相关资源