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 をクリックします。本人確認のコードがメールで届き、その後 Consumer Key が表示されます。これが MailInApp に必要な発行者です。シークレットは不要です。
MailInApp がログインするユーザーには、そのユーザーが Salesforce で見られるものだけが見えます。メールで使うオブジェクトに読み取り権限を持つ専用の連携ユーザーにするのがいちばんきれいです。そのユーザーから(項目レベルセキュリティで)隠れている項目は、クエリ結果に含まれません。
MailInApp で接続する
データソース → + API 接続 を開き、次のように設定します。
- エンドポイント URL:組織のクエリ URL に 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。
- トークン URL:
https://login.salesforce.com/services/oauth2/token(または My Domain のhttps://yourorg.my.salesforce.com/services/oauth2/token)。Sandbox ではhttps://test.salesforce.com/services/oauth2/token。 - 発行者:アプリの Consumer Key。
- サブジェクト:MailInApp がログインする Salesforce のユーザー名。
- オーディエンス(aud):
https://login.salesforce.com(Sandbox ではhttps://test.salesforce.com)。 - 秘密鍵:
mailinapp.keyの中身。
- トークン URL:
この設定をテスト をクリックすると、実際にトークンを取得してクエリを実行し、差し込みタグから見えるとおりの最初の数行を表示します。保存後は、保存済みの接続をテスト で鍵を貼り直さずにいつでも確認できます。
1 つの接続は 1 つのクエリです。用途ごとに作成します。パイプラインのメールには商談、商品カタログには価格表、オーディエンスには連絡先、という具合です。
SOQL でのクエリ
クエリがそのまま受け取るデータになります。メールに必要な列だけを選んでください。
- 関連項目も使えます。 Salesforce は
Account.Nameのような参照項目を入れ子のオブジェクトで返しますが、MailInApp はそれをAccount.Nameという名前の項目にします。差し込みタグでは{{alias.Account.Name}}、繰り返しブロックの中では{{Account.Name}}と書きます。3 階層(Account.Owner.Name)まで対応し、Salesforce が各レコードに付けるattributesのメタデータは除かれます。 - 並べ替えと件数はクエリで。
ORDER BY CloseDateとLIMIT 10で、繰り返しブロックに表示する行の順序と数が決まります。 - 1 回の取得で最大 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}}は最初の行から解決されます。見出しの数字 1 つに向いています。 - 繰り返し行:繰り返しブロックに渡され、行ごとに中身を繰り返します。たとえば商品ごとに 1 枚のカードです。
- 同じ行は KPI・棒・折れ線・円グラフにも使えます。
Amountを合計する KPI は進行中パイプラインのライブな数字に、StageNameでまとめた棒グラフはステージ別のパイプラインになります。
受信者ごとに違う切り口を見せる
繰り返しブロックの 行をフィルター とグラフのフィルターでは、Salesforce の項目を受信者自身のデータと比べられます。company 列を持つオーディエンスリストなら、Account.Name が次と等しい {{company}} というルールで、各販売店に自社の商談だけを見せられます。クエリは 1 つで共通です。各受信者のメールは、送信時にその人の行から作られます。
Salesforce の連絡先をインポートする
オーディエンスは MailInApp の連絡先リストです。Salesforce から埋めるには、Contact のクエリ(上の 3 つ目)で API 接続を作り、連絡先 → 連絡先をインポート で API接続 を選びます。
MailInApp は保存済みの認証情報で行を読み込み、Salesforce の項目を認識して Salesforce の対応付けを使う を提案します。FirstName → first_name、Account.Name → company、Id → salesforce_id などです。Salesforce で Email Opt Out(HasOptedOutOfEmail)がオンの連絡先は確認ステップで示され、除外するか選べます。CSV で書き出した Salesforce レポートも同じように認識されます。リードのインポートもご覧ください。
インポートはコピーです。新しい連絡先を取り込むには、もう一度実行します。
この接続で作る週次のパイプラインダイジェストの例は、Salesforce のライブデータで動くインタラクティブメールをご覧ください。
