本文详解 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><div class="aritcle_card flexRow artxards">
<div class="artcardd flexRow">
<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill9722" title="plan-hvac-service-company-local-seo-faq-cluster"><img
src="https://img.php.cn/upload/skill/001/246/273/6adaf20dbae7c507.jpg" alt="plan-hvac-service-company-local-seo-faq-cluster" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill9722" title="plan-hvac-service-company-local-seo-faq-cluster" class="overflowclass">plan-hvac-service-company-local-seo-faq-cluster</a>
<p class="overflowclass">调研本地问题，聚类分组，为暖通空调公司撰写可直接发布的FAQ，适用于本地SEO工作。</p>
</div>
<a rel="nofollow" href="/xiazai/skill9722" title="plan-hvac-service-company-local-seo-faq-cluster" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div>",
"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 + 必填字段，确认日记条目即时生成，再逐步叠加模板、附件等高级功能。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
