本文详解 ServiceM8 平台中通过 /platform_service_email API 发送邮件后无法在工单日记（Job Diary）中显示的根本原因——关键参数命名变更，并提供完整验证步骤、正确请求示例及最佳实践建议。
本文详解 servicem8 平台中通过 `/platform_service_email` api 发送邮件后无法在工单日记（job diary）中显示的根本原因——关键参数命名变更，并提供完整验证步骤、正确请求示例及最佳实践建议。
在集成 ServiceM8 API 进行业务自动化时，一个常见却易被忽视的问题是：调用 POST /platform_service_email 接口返回 200 OK，收件人也正常收到邮件，但该邮件未出现在对应工单的“日记”（Diary）标签页中，导致业务上下文断裂、审计困难、客户沟通链路不可追溯。
根据 ServiceM8 官方最新 API 文档（截至 2026 年 10 月有效版本），问题根源在于参数字段名已更新：旧版文档或历史代码中常误用 "job_uuid" 作为关联工单的字段，而当前生产环境强制要求使用 "regardingJobUUID"（注意大小写与下划线）。该字段为必填项，且仅当其值为合法、存在且状态有效的工单 UUID 时，API 才会将该邮件持久化绑定至该工单的日记记录中。
✅ 正确请求示例（含关键修正）：
{
"to": "client@example.com",
"from": "your@company.com",
"subject": "It works",
"message": "This message confirms Email was sent correctly",
"htmlBody": "<p>This message confirms Email was sent correctly</p>",
"textBody": "This message confirms Email was sent correctly",
"regardingJobUUID": "7c950fdd-7cbf-4b87-ad9b-2294227485db",
"template_uuid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"
}⚠️ 注意事项与补充说明：
-
"regardingJobUUID"是唯一有效的工单关联字段；"job_uuid"、"jobId"、"job"等均为无效别名，即使值正确也不会触发日记绑定。 - 虽然
"template_uuid"可增强邮件结构一致性，但它不能替代regardingJobUUID的关联作用；二者职责分离——模板控制内容样式，regardingJobUUID控制业务归属。 - 认证方式不影响日记绑定逻辑：ServiceM8 当前同时支持 Basic Auth（用户名+密码）和 Bearer Token（OAuth 2.0），只要凭证有效，日记关联行为完全取决于请求体字段是否合规。
- 建议在发送前增加校验逻辑：通过
GET /job/{uuid}接口预检目标工单是否存在、是否处于Active或Completed状态（非Archived或Deleted），避免因工单状态异常导致静默失败。 - 若仍不显示，请检查 ServiceM8 后台设置：进入 Settings → Company Settings → Email → “Log emails to job diary” 是否已启用（默认开启，但企业管理员可能关闭）。
? 总结：这不是权限、网络或认证问题，而是典型的API 字段契约演进导致的兼容性断层。务必以 ServiceM8 官方最新 API 参考文档 为准，而非旧项目代码或第三方博客。每次升级集成前，建议执行一次最小化测试——仅传 regardingJobUUID + 必填字段，确认日记条目即时生成，再逐步叠加模板、附件等高级功能。
