mailinapp
Documentation menu

Salesforce

MailInApp 没有需要安装的 Salesforce 应用——你也不需要它。Salesforce 自己的 REST API 会通过 HTTPS 返回纯 JSON,MailInApp 的API 数据源搭配 OAuth2 JWT Bearer 认证方式,正是为直接对接 Salesforce 的服务器到服务器登录流程而构建的:无需交互式授权页面,无需照看刷新令牌,你的 Salesforce 密码也绝不会经过 MailInApp。

本指南搭建的是一个只读连接——把 Opportunity、Account 或 Contact 行数据拉取到合并标签、重复模块,以及实时绑定的图表模块中。它不会向 Salesforce 写回任何内容。

连接的工作原理

  1. MailInApp 使用你 Salesforce 连接应用(Connected App)的私钥对一个短期有效的 JWT 断言进行签名。
  2. 它将该断言 POST 到 Salesforce 的令牌端点,该端点会根据你上传的证书验证签名,并返回一个访问令牌——从不发送任何用户名或密码。
  3. MailInApp 会缓存该访问令牌,并将其作为 Bearer 令牌调用 Salesforce REST API(执行一次 SOQL 查询),在令牌过期前,或某次调用返回未授权时,自动刷新令牌。

每一步都在服务器端进行,且发生在每一次拉取时——一旦设置完成,就不需要手动保持连接或重新授权。

在 Salesforce 一侧完成设置

  1. 在 Salesforce Setup 中,前往App Manager → New Connected App(或New Connected App (Lightning))。
  2. 填写基本的名称/邮箱字段,然后勾选Enable OAuth Settings。
  3. 在Use digital signatures下,上传一个证书。如果你还没有,生成一个自签名证书及其配套的 RSA 私钥——证书上传到 Salesforce,私钥填入 MailInApp。请把私钥保存在安全的地方;你只需要粘贴到 MailInApp 一次,之后就会被遮蔽。
  4. 添加你的集成所需的 OAuth 范围——读取记录只需要 api(通过 API 管理用户数据)即可。
  5. 保存后,编辑该连接应用的策略:将Permitted Users 设置为 Admin approved users are pre-authorized。正是这一项设置让整个流程无需人工交互——否则 Salesforce 会要求人工点击一个授权页面,而这是服务器到服务器的 JWT 交换所无法完成的。
  6. 通过权限集(permission set)将集成用户(一个已在其个人资料上启用 API 访问的真实 Salesforce 用户,或一个专用的集成账号)分配给该连接应用。
  7. 记下该连接应用的Consumer Key——这就是 MailInApp 所需的 issuer——以及你所在组织的My Domain URL(Setup → My Domain),例如 https://yourorg.my.salesforce.com。

在 MailInApp 中完成连接

在数据源 → + API 连接中,设置:

  • 端点——你所在组织的 REST 查询 URL,例如 https://yourorg.my.salesforce.com/services/data/v61.0/query?q=SELECT+Name,Amount,StageName,CloseDate+FROM+Opportunity+WHERE+IsClosed+=+false(一个经过 URL 编码的 SOQL 查询——见下方使用 SOQL 查询)。
  • 数据路径——records。Salesforce 的查询响应会把实际行数据包裹在一个 records 数组中,并附带 totalSize/done 字段。
  • 身份验证——OAuth2 JWT Bearer:
    • 令牌 URL——生产环境和 Developer Edition 组织使用 https://login.salesforce.com/services/oauth2/token,沙盒环境使用 https://test.salesforce.com/services/oauth2/token。
    • 签发者——该连接应用的 Consumer Key。
    • 主体——集成用户的 Salesforce 用户名(JWT 所断言的身份)。
    • 受众——与令牌 URL 相同的主机:https://login.salesforce.com(沙盒环境为 https://test.salesforce.com)。
    • 私钥——与你上传到连接应用的证书配套的 RSA 私钥。

点击测试这些设置可以在保存前确认连接——它会真实铸造一个令牌并预览前几行数据。保存后,可以随时使用测试已保存的连接重新检查连接,而不需要重新粘贴私钥。

使用 SOQL 查询

端点的查询字符串本身就是你得到的数据——没有单独的"选择字段"界面,因此需要把 SOQL 查询本身调整成正好返回你邮件所需的列:

SELECT Name, Amount, StageName, CloseDate FROM Opportunity WHERE IsClosed = false

关于返回数据的结构,有几点需要了解:

  • **仅支持扁平字段。**类似 Owner.Email 或 Account.Name 这样的关系字段,会以嵌套 JSON 对象的形式返回({"Owner": {"Email": "..."}}),而 MailInApp 的行解析器会直接丢弃嵌套值,而不会尝试猜测如何将其扁平化。如果你需要一个可用作合并标签的所有者或账户标识,请改选一个扁平字段——例如 OwnerId——而不是一个带点号的关系路径。
  • **每次拉取最多 1,000 行。**对于摘要或仪表盘类邮件已经足够;如果你只想要特定的一部分数据,可以在查询本身中用 WHERE/ORDER BY/LIMIT 进一步缩小范围。
  • **每次渲染都会重新拉取最新数据。**一次定时发送会重新运行该查询,并在每次发送时用 Salesforce 当前的行数据重新渲染已绑定的模块——除了 OAuth 令牌本身之外,不存在任何额外的缓存。

使用数据

连接完成后,从工作室的数据面板将其添加到项目中,并设置一个别名(例如 pipeline)和一个角色:

  • 合并字段会从返回的第一行数据中解析出 {{pipeline.field}}——适合用于单个标题性数字。
  • 重复行为重复模块提供数据——每个 Opportunity 一行,以列表或表格形式渲染。
  • collection 角色绑定正是KPI 摘要卡、柱状图、折线图和饼图模块直接绑定的对象——把 KPI 摘要卡的数值字段设置为 Amount 并选择求和聚合方式,就能得到一个实时的"未结总管道金额"数字,完全不需要任何合并标签配置;而按 StageName 分组的柱状图,则能把同一个查询变成按阶段划分的管道分布图。

完整实例见由实时 Salesforce 数据驱动的互动邮件——一份完全基于此连接构建的每周管道摘要邮件。