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에 필요한 발급자입니다. 시크릿은 필요 없습니다.
MailInApp이 로그인하는 사용자는 그 사용자가 Salesforce에서 볼 수 있는 것만 봅니다. 이메일에서 쓰는 개체에 읽기 권한이 있는 전용 연동 사용자가 가장 깔끔합니다. 그 사용자에게 (필드 수준 보안으로) 숨겨진 필드는 쿼리 결과에 나오지 않습니다.
MailInApp에서 연결하기
데이터 소스 → + API 연결로 가서 다음을 입력합니다.
- 엔드포인트 URL: SOQL 쿼리가 붙은 조직의 쿼리 URL. 예:
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). 샌드박스는https://test.salesforce.com/services/oauth2/token. - 발급자: 앱의 Consumer Key.
- 주체: MailInApp이 로그인할 Salesforce 사용자 이름.
- 대상(audience):
https://login.salesforce.com(샌드박스는https://test.salesforce.com). - 개인 키:
mailinapp.key의 내용.
- 토큰 URL:
이 설정 테스트를 클릭하면 실제 토큰을 받아 쿼리를 실행하고, 병합 태그가 보게 될 그대로 처음 몇 행을 보여 줍니다. 저장한 뒤에는 저장된 연결 테스트로 키를 다시 붙여 넣지 않고 언제든 확인할 수 있습니다.
연결 하나는 쿼리 하나입니다. 용도마다 하나씩 만드세요. 파이프라인 이메일에는 진행 중인 영업 기회, 제품 카탈로그에는 가격표, 대상 목록에는 연락처를 씁니다.
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 실시간 데이터로 움직이는 인터랙티브 이메일에서 볼 수 있습니다.
