Salesforce
MailInApp 没有需要安装的 Salesforce 应用,你也不需要。Salesforce 的 REST API 通过 HTTPS 返回普通 JSON。MailInApp 的 API 数据源使用 OAuth2 JWT Bearer 认证,直接对接 Salesforce 的服务器到服务器登录流程:没有授权确认页,不用管理刷新令牌,你的 Salesforce 密码也永远不会到达 MailInApp。
本指南设置一个只读连接。它把 Opportunity、Account、Contact 或产品数据行带入合并标签、重复模块和绑定数据的图表,还可以把 Salesforce 联系人导入为受众。它不会向 Salesforce 写入任何内容。
连接的工作方式
- MailInApp 用你应用的私钥签署一个短时有效的 JWT 断言。
- 它把断言发送到 Salesforce 的令牌端点,Salesforce 用你上传的证书校验签名并返回访问令牌。不会发送任何用户名或密码。
- 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 默认是关闭的)。
- 在设置(Setup)中打开 External Client App Manager,点击 New External Client App。
- 填写名称(例如 MailInApp JWT)和联系邮箱,Distribution State 保持为 Local。
- 打开 API (Enable OAuth Settings) 并勾选 Enable OAuth。JWT 流程不会用到 Callback URL,但它是必填项:填
https://login.salesforce.com/services/oauth2/success即可。 - 在 OAuth Scopes 中添加 Manage user data via APIs (api) 和 Perform requests at any time (refresh_token, offline_access)。
- 在 Flow Enablement 中勾选 Enable JWT Bearer Flow,并上传证书(
mailinapp.crt)。点击 Create。 - 在应用的 Policies 标签页点击 Edit。在 OAuth Policies 中把 Permitted Users 设为 Admin approved users are pre-authorized,然后选择 MailInApp 登录所用用户的简档或权限集。正是这一步让流程无需交互:否则 Salesforce 会等待有人在授权页面上确认。保存。
- 在 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 实时数据驱动的交互式邮件:一封基于此连接的每周管道摘要。
