文档菜单

Salesforce

MailInApp 没有需要安装的 Salesforce 应用,你也不需要。Salesforce 的 REST API 通过 HTTPS 返回普通 JSON。MailInApp 的 API 数据源使用 OAuth2 JWT Bearer 认证,直接对接 Salesforce 的服务器到服务器登录流程:没有授权确认页,不用管理刷新令牌,你的 Salesforce 密码也永远不会到达 MailInApp。

英文视频

本指南设置一个只读连接。它把 Opportunity、Account、Contact 或产品数据行带入合并标签、重复模块和绑定数据的图表,还可以把 Salesforce 联系人导入为受众。它不会向 Salesforce 写入任何内容。

连接的工作方式

  1. MailInApp 用你应用的私钥签署一个短时有效的 JWT 断言。
  2. 它把断言发送到 Salesforce 的令牌端点,Salesforce 用你上传的证书校验签名并返回访问令牌。不会发送任何用户名或密码。
  3. MailInApp 缓存访问令牌,并用它调用 Salesforce REST API(一条 SOQL 查询)。令牌过期前,或某次调用返回未授权时,会重新获取。

一切都在服务器端、每次读取时完成。设置好之后,不需要维护或重新授权。

创建密钥对

JWT 流程需要一对 RSA 密钥:证书交给 Salesforce,私钥交给 MailInApp。如果还没有,可以用 OpenSSL 生成一对自签名密钥:

openssl req -x509 -newkey rsa:2048 -nodes -keyout mailinapp.key -out mailinapp.crt -days 730 -subj "/CN=MailInApp"

请妥善保存 mailinapp.key。你只需在 MailInApp 中粘贴一次,之后它会被隐藏。

设置 Salesforce

Salesforce 现在以 External Client Apps 的形式创建新的集成(在较新的组织中,新建 Connected App 默认是关闭的)。

  1. 在设置(Setup)中打开 External Client App Manager,点击 New External Client App。
  2. 填写名称(例如 MailInApp JWT)和联系邮箱,Distribution State 保持为 Local。
  3. 打开 API (Enable OAuth Settings) 并勾选 Enable OAuth。JWT 流程不会用到 Callback URL,但它是必填项:填 https://login.salesforce.com/services/oauth2/success 即可。
  4. 在 OAuth Scopes 中添加 Manage user data via APIs (api) 和 Perform requests at any time (refresh_token, offline_access)。
  5. 在 Flow Enablement 中勾选 Enable JWT Bearer Flow,并上传证书(mailinapp.crt)。点击 Create。
  6. 在应用的 Policies 标签页点击 Edit。在 OAuth Policies 中把 Permitted Users 设为 Admin approved users are pre-authorized,然后选择 MailInApp 登录所用用户的简档或权限集。正是这一步让流程无需交互:否则 Salesforce 会等待有人在授权页面上确认。保存。
  7. 在 Settings 标签页打开 OAuth Settings,点击 Consumer Key and Secret。Salesforce 会通过邮件发送验证码确认身份,然后显示 Consumer Key:这就是 MailInApp 需要的签发者。不需要密钥(secret)。

MailInApp 登录所用的用户,只能看到该用户在 Salesforce 中能看到的内容。最干净的做法是一个专用的集成用户,对你的邮件用到的对象有读取权限。对该用户隐藏的字段(字段级安全)不会出现在查询结果中。

在 MailInApp 中连接

前往 数据源 → + API 连接,填写:

  • 端点网址:你组织的查询网址加一条 SOQL 查询,例如 https://yourorg.my.salesforce.com/services/data/v62.0/query?q=SELECT Name, Amount, StageName, CloseDate, Account.Name FROM Opportunity WHERE IsClosed = false。查询可以直接用普通空格输入,MailInApp 会自动编码。
  • 数据路径:records。Salesforce 把数据行放在 records 数组中,旁边是 totalSize 和 done。
  • 身份验证:OAuth2 JWT Bearer,并填写:
    • 令牌网址:https://login.salesforce.com/services/oauth2/token(或你的 My Domain 的 https://yourorg.my.salesforce.com/services/oauth2/token);沙盒用 https://test.salesforce.com/services/oauth2/token。
    • 签发者:应用的 Consumer Key。
    • 主体:MailInApp 登录所用的 Salesforce 用户名。
    • 受众(Audience):https://login.salesforce.com(沙盒用 https://test.salesforce.com)。
    • 私钥:mailinapp.key 的内容。

点击 测试这些设置:MailInApp 会获取真实令牌、运行查询,并按合并标签看到的样子显示前几行。保存后,测试已保存的连接 可以随时检查,无需重新粘贴私钥。

一个连接就是一条查询。每个用途建一个:管道邮件用未关闭的商机,产品目录用价格手册,受众用联系人。

用 SOQL 查询

查询就是你拿到的数据,只选择邮件需要的列。

  • 关联字段可以使用。 Salesforce 会把 Account.Name 这样的关系字段作为嵌套对象返回,MailInApp 会把它变成名为 Account.Name 的字段。在合并标签里写作 {{alias.Account.Name}},在重复模块里写作 {{Account.Name}}。最多支持三层(Account.Owner.Name),Salesforce 给每条记录附加的 attributes 元数据会被略去。
  • 在查询中排序和限制数量。 ORDER BY CloseDate 和 LIMIT 10 决定重复模块显示的行顺序和行数。
  • 每次读取最多 1,000 行,做摘要或目录足够了。
  • 每次渲染都重新读取。 每次发送(包括定期发送的每一次)都会重新运行查询,所以邮件总是显示 Salesforce 的最新数据。只有 OAuth 令牌会被缓存。

几条实用的查询:

SELECT Name, StageName, Amount, CloseDate, NextStep, Account.Name FROM Opportunity WHERE IsClosed = false ORDER BY CloseDate
SELECT Name, ProductCode, UnitPrice, Product2.Description, Product2.DisplayUrl FROM PricebookEntry WHERE Pricebook2.IsStandard = true AND IsActive = true
SELECT Id, FirstName, LastName, Title, Email, HasOptedOutOfEmail, Account.Name, Account.Industry FROM Contact WHERE AccountId != null

使用数据

在工作室的数据面板中,用一个别名(例如 pipeline)和一个角色把连接加到邮件里:

  • 合并字段:{{pipeline.field}} 取第一行的值,适合单个关键数字。
  • 重复行:提供给重复模块,它会为每一行重复其内容,例如每个产品一张卡片。
  • 同样的行也可以驱动 KPI、柱状、折线和饼图:对 Amount 求和的 KPI 是实时的未关闭管道金额,按 StageName 分组的柱状图就是各阶段的管道。

每位收件人看到不同的部分

重复模块的 筛选行 和图表的筛选器,可以把 Salesforce 字段与收件人自己的数据比较。如果受众列表有 company 列,规则 Account.Name 等于 {{company}} 会让每位零售商只看到自己的商机,而查询只有一条、大家共用。每位收件人的邮件都在发送时用其自己的数据行生成。

导入你的 Salesforce 联系人

受众是 MailInApp 的联系人列表。要从 Salesforce 填充它,先用 Contact 查询(上面第三条)创建一个 API 连接,然后前往 联系人 → 导入联系人 并选择 API 连接。

MailInApp 会用已保存的凭据读取数据行,识别 Salesforce 字段,并提供 使用 Salesforce 映射:FirstName → first_name、Account.Name → company、Id → salesforce_id 等。在 Salesforce 中勾选了 Email Opt Out(HasOptedOutOfEmail)的联系人会在验证步骤中被标出,你可以选择不导入。以 CSV 导出的 Salesforce 报表也会以同样方式识别。参见导入潜在客户。

导入是一份副本:再运行一次即可带入新联系人。

完整示例请看由 Salesforce 实时数据驱动的交互式邮件:一封基于此连接的每周管道摘要。