Salesforce Email Sync：开发者和管理员的技术指南

Source: Dev.to

请提供您希望翻译的正文内容，我将为您翻译成简体中文。

Source: …

Salesforce Email Sync 概览

Salesforce Email Sync 表面看起来很简单，但其技术深度足以让即使是有经验的管理员也会卡住。了解电子邮件活动同步的内部工作原理可以为您节省数小时的调试时间，并减少用户投诉。

什么是 Salesforce Email Sync？

Salesforce Email Sync 从外部邮件客户端（Gmail、Outlook 等）捕获电子邮件活动，并将其存储为 Salesforce CRM 中的活动记录。它不需要代表手动记录每封邮件，而是创建一个 单向或双向桥梁，将邮件客户端与 CRM 连接起来。

• 数据模型 – 同步的邮件存储为 EmailMessage 或 Task 记录（取决于配置）。
• 关联 – 记录通过电子邮件地址匹配链接到相应的 Contact、Lead、Account、Opportunity 或自定义对象。

主要框架

提示： 您使用的框架取决于组织的版本和需求。可能只使用一种、两种或全部三种。

Salesforce 邮件同步工作原理

数据流架构

Mail Client (Gmail / Outlook)
        │
        ▼
OAuth 2.0 Authentication
        │
        ▼
Salesforce Sync Service (Einstein Activity Capture)
        │
        ▼
Email Matching Engine (by email address)
        │
        ▼
Activity Records in Salesforce (EmailMessage / Task)
        │
        ▼
Associated to: Contact, Lead, Account, Opportunity

1. 用户连接 他们的 Gmail 或 Outlook 账户。
2. Salesforce 请求 OAuth 2.0 范围 以读取邮件元数据和内容。
3. EAC 轮询或监听 新活动，并将匹配的记录推送到组织中。

邮件地址匹配

• Salesforce 使用 Contact 和 Lead 对象上的 Email 字段，将收发邮件与 CRM 记录匹配。
• 如果线程中的地址未匹配到任何记录，邮件仍会同步，但 不会自动关联；它仅出现在已连接用户的活动时间线中。

示例：查询通过 EAC 同步的 EmailMessage 记录

List<EmailMessage> syncedEmails = [
    SELECT Id, Subject, FromAddress, ToAddress, ActivityId, RelatedToId
    FROM EmailMessage
    WHERE CreatedDate = LAST_N_DAYS:7
      AND Incoming = true
    LIMIT 50
];

for (EmailMessage em : syncedEmails) {
    System.debug('From: ' + em.FromAddress + ' | Related To: ' + em.RelatedToId);
}

• 当未找到匹配记录时，RelatedToId 将为 null ——这对于诊断未匹配的同步记录很有帮助。

支持的平台和同步方式

关键特性与功能

Note: 您可以在仅需要邮件记录的情况下，仅启用邮件同步 而不 启用联系人或日历同步。

故障排除提示

1. 未匹配的电子邮件 – 验证该电子邮件地址是否存在于联系人/潜在客户记录中（包括次要电子邮件字段）。
2. 数据可见性 – 因为 EAC 将数据存储在单独的存储中，EmailMessage 记录可能不计入组织的数据存储限制，但它们 不可通过标准全局搜索。使用 Einstein Activity Capture 报告或在 SOQL 中查询 Email Message 对象。
3. 同步延迟 – 常规同步间隔为几分钟；大量邮件会导致轻微延迟。
4. OAuth 范围 – 确保已连接的应用具有正确的范围（例如 mail.read、mail.send）。如果用户报告缺少邮件，请重新进行身份验证。
5. 版本兼容性 – 对于本地部署的 Exchange，请确认 EWS 端点受您当前的 Salesforce 版本支持。

快速参考代码片段

// Find EmailMessages without a related record (unmatched)
List<EmailMessage> unmatched = [
    SELECT Id, Subject, FromAddress, ToAddress, CreatedDate
    FROM EmailMessage
    WHERE RelatedToId = null
      AND CreatedDate = LAST_N_DAYS:30
];

System.debug('Unmatched email count: ' + unmatched.size());

使用此查询可以找出需要手动关联的电子邮件，或识别联系人数据中的空白。

要点： 精通 Salesforce 邮件同步的工作原理——尤其是匹配引擎和存储模型——能够显著降低支持工单数量，让您的销售和支持团队专注于销售，而不是记录日志。

Salesforce 邮件同步的好处

• Reduced null fields on activity records – Automated sync enforces consistent data capture.
• Accurate LastActivityDate on Leads and Contacts – Keeps automation processes (lead aging, re‑engagement workflows) current.
• Better signal for automation – Reliable email‑activity data improves Process Builder and Flow reliability.
• Reporting accuracy – Email‑engagement metrics reflect actual behavior rather than manually entered data.

如何设置 Salesforce 邮件同步

前置条件

• 包含 Einstein Activity Capture（EAC）的 Salesforce 版本（Sales Cloud，部分 Professional 及以上版本）
• 在 Google Workspace 或 Microsoft 365 管理中心配置的已连接应用（Connected App）
• Salesforce 管理员权限

步骤 1 – 启用 Einstein Activity Capture

1. 前往：Setup → Einstein Activity Capture → Settings → Enable Einstein Activity Capture
2. 选择你的邮件提供商（Google 或 Microsoft），并按照 OAuth 配置步骤操作。
3. 在邮件提供商的管理控制台中将 Salesforce 注册为授权应用。

步骤 2 – 配置同步设置

Setup → Einstein Activity Capture → Settings → Configuration

提示： 可通过 Apex 或 REST API 验证 EAC 是否已启用，并使用 ConnectedApplication 或 OAuthToken 检查已连接的用户。

步骤 3 – 分配用户

每位用户必须连接其邮件账户：User Settings → Einstein Activity Capture → Connect Account

此操作需用户自行完成；管理员无法代替用户连接账户，因为受 OAuth 要求限制。

步骤 4 – 配置共享设置

EAC 邮件默认 私有。根据需要调整共享，以便经理和团队成员查看相应的活动：

Setup → Einstein Activity Capture → Settings → Sharing

选项：

• 私有
• 仅内部
• 所有人

常见挑战与故障排除

同步延迟

EAC 不是实时的。典型延迟为 2–10 分钟，但在负载较高时可能更长。如果用户报告缺少邮件，请检查：

1. 用户的账户是否仍然已连接？（OAuth 令牌可能已过期或被撤销）
2. 邮件地址是否与 Salesforce 中的记录匹配？
3. 邮件是否被排除规则过滤？

对 EAC 数据的 SOQL 限制

EAC 将邮件存储在 外部数据存储 中，而不是标准的 Salesforce 对象中。因此：

// This will NOT return EAC‑synced emails in many configurations
// Use ActivityHistory or the UI timeline to verify synced data

• 标准 SOQL 不能直接查询 EAC 数据存储。
• 如需编程访问，请使用 Einstein Activity Capture REST API。

权限问题

常见的权限错误通常源于缺少 Einstein Activity Capture 用户权限或配置文件/权限集分配不正确。

数据隐私考虑

EAC 同步的是邮件 内容，而不仅仅是元数据，因此需注意 GDPR、CCPA 等法规：

• 在同步设置中排除个人电子邮件域名。
• 定义数据保留策略（EAC 默认保留 24 个月 的数据）。
• 查看 Salesforce 的数据处理协议，以满足受监管行业的要求。

Best Practices for Salesforce Email Sync

1. Configure exclusion lists before go‑live (internal addresses, HR, legal domains).
   在上线前配置排除列表（内部地址、HR、法律域）。

2. Use permission sets (not profiles) to manage EAC access for granular rollout control.
   使用权限集（而非配置文件）来管理 EAC 访问，以实现细粒度的发布控制。

3. Monitor OAuth token health programmatically or via Salesforce Health Check—expired tokens are the top cause of sync outages.
   通过编程方式或使用 Salesforce Health Check 监控 OAuth 令牌健康——令牌过期是同步中断的主要原因。

4. Start with one‑way sync; enable bi‑directional only after validating data quality.
   首先使用单向同步；在验证数据质量后再启用双向同步。

5. Document matching logic—know which objects/fields EAC uses to associate emails. Custom email fields may need supplemental automation.
   记录匹配逻辑——了解 EAC 用于关联邮件的对象/字段。自定义邮件字段可能需要额外的自动化。

6. Test in a sandbox first; EAC can be enabled with test Google or Microsoft accounts. Validate exclusion rules and sharing settings before production.
   首先在沙盒中测试；EAC 可使用测试的 Google 或 Microsoft 账户启用。在投入生产前验证排除规则和共享设置。

7. Plan for EAC’s storage model—standard data export/backup tools don’t capture EAC data. Include this in your data‑governance documentation.
   为 EAC 的存储模型做好规划——标准的数据导出/备份工具无法捕获 EAC 数据。请将其纳入数据治理文档。

结论

当正确配置时，Salesforce Email Sync（Einstein Activity Capture）提供了一种低摩擦的方式来保持 CRM 数据的实时更新。需要提前做好以下关键要素：

• 排除规则
• 共享设置
• 理解 EAC 的外部数据模型

锁定这些要点后，后续的实施就会变得直截了当。

对于邮件量大、需要自定义对象关联或有高级投递需求的组织，建议评估专为此设计的 Salesforce 邮件工具，以扩展或替代原生 EAC。