ServiceM8 平台中调用 /platform_service_email 接口发送邮件返回 200 OK 且收件人正常收到，但邮件未出现在对应工单（Job）的日记（Diary）中，根本原因在于请求体中使用了过时或错误的字段名——正确参数应为 regardingJobUUID，而非 job_uuid。
servicem8 平台中调用 `/platform_service_email` 接口发送邮件返回 200 ok 且收件人正常收到，但邮件未出现在对应工单（job）的日记（diary）中，根本原因在于请求体中使用了过时或错误的字段名——正确参数应为 `regardingjobuuid`，而非 `job_uuid`。
在 ServiceM8 的平台邮件 API（POST https://api.servicem8.com/platform_service_email）中，将邮件与特定工单建立上下文关联是可选但关键的行为。若未提供合法且语义正确的工单标识字段，系统虽会成功投递邮件（因此返回 HTTP 200），但该邮件将作为“独立通信”存入联系人档案或全局日志，而不会出现在目标工单的「Job Diary」标签页下——这正是用户观察到“邮件已发、却查无此信”的核心症结。
✅ 正确做法：使用 regardingJobUUID 字段（注意大小写与下划线）
该字段是 ServiceM8 官方文档明确指定的标准关联字段，用于声明该邮件所归属的工单实体。其值必须为有效的 UUID 格式字符串（如 7c950fdd-7cbf-4b87-ad9b-2294227485db），且对应工单需存在于当前账户中。
以下是修正后的请求体示例（JSON）：
{
"to": "client@example.com",
"from": "you@yourcompany.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">
<div class="artcardd flexRow">
<a class="aritcle_card_img" 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" ></a>
<div class="aritcle_card_info flexColumn">
<a href="/xiazai/skill9722" title="plan-hvac-service-company-local-seo-faq-cluster">plan-hvac-service-company-local-seo-faq-cluster</a>
<p>调研本地问题，聚类分组，为暖通空调公司撰写可直接发布的FAQ，适用于本地SEO工作。</p>
</div>
<a 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"
}⚠️ 注意事项：
-
job_uuid是无效字段名，ServiceM8 API 将完全忽略它，不报错也不生效； -
template_uuid仅控制邮件模板渲染逻辑，无法替代工单关联功能，故单独添加无效； - 身份认证方式（Basic Auth 用户名/密码 vs. Bearer Token）不影响关联逻辑，只要认证有效即可；但建议优先使用 OAuth 2.0 访问令牌以符合安全最佳实践；
- 若
regardingJobUUID值为空、格式非法（如缺少连字符）、或指向不存在/权限不可见的工单，API 仍可能返回 200，但邮件将降级为“无关联邮件”，请务必校验 UUID 来源与有效性。
? 补充验证建议：
- 使用 ServiceM8 API Explorer 手动构造请求，确认
regardingJobUUID是否能触发日记条目生成； - 检查目标工单详情页 → 「Diary」选项卡 → 筛选类型为 “Email”，确认新条目是否出现；
- 查看响应头中的
X-Request-ID，必要时向 ServiceM8 支持团队提供该 ID 追踪后台处理行为。
总结：ServiceM8 的平台邮件 API 设计强调显式语义——不是所有含“job”字样的字段都具备关联能力。唯有 regardingJobUUID 是被引擎识别并用于日记归档的权威字段。及时更新集成代码中的字段命名，是确保业务通信与工单生命周期精准对齐的关键一步。
