mailinapp
Documentation menu

Salesforce

MailInApp에는 설치할 별도의 Salesforce 앱이 없습니다 — 필요하지도 않습니다. Salesforce 자체의 REST API는 HTTPS를 통해 평범한 JSON으로 응답하며, OAuth2 JWT Bearer 인증을 사용하는 MailInApp의 API 데이터 소스는 Salesforce의 서버 간 로그인 흐름을 직접 구사하도록 만들어졌습니다: 대화형 동의 화면도 없고, 관리해야 할 리프레시 토큰도 없으며, Salesforce 비밀번호가 MailInApp에 전달되는 일도 전혀 없습니다.

이 가이드는 읽기 전용 연결을 설정합니다 — Opportunity, Account, 또는 Contact 행을 병합 태그, 반복 블록, 실시간 연동 차트 블록으로 가져옵니다. Salesforce에 다시 쓰지는 않습니다.

연결 작동 방식

  1. MailInApp이 여러분의 Salesforce Connected App 개인 키로 단명 JWT 어설션에 서명합니다.
  2. 그 어설션을 Salesforce의 토큰 엔드포인트에 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(Manage user data via APIs)로 충분합니다.
  5. 저장한 다음, Connected App의 정책을 편집해 Permitted Users를 Admin approved users are pre-authorized로 설정합니다. 이 설정이 바로 흐름을 비대화형으로 만들어 주는 부분입니다 — 이 설정이 없으면 Salesforce는 사람이 동의 화면을 클릭해 통과하기를 기대하는데, 서버 간 JWT 교환은 이를 할 수 없습니다.
  6. 연동 사용자(프로필에서 API 액세스가 활성화된 실제 Salesforce 사용자, 또는 연동 전용 사용자)를 권한 세트를 통해 Connected App에 할당합니다.
  7. Connected App의 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의 쿼리 응답은 실제 행을 totalSize/done 필드와 함께 records 배열로 감쌉니다.
  • 인증 — OAuth2 JWT Bearer:
    • 토큰 URL — 프로덕션 및 Developer Edition 조직은 https://login.salesforce.com/services/oauth2/token, 샌드박스는 https://test.salesforce.com/services/oauth2/token입니다.
    • 발급자(Issuer) — Connected App의 Consumer Key입니다.
    • 주체(Subject) — 연동 사용자의 Salesforce 사용자명입니다(JWT가 주장하는 신원입니다).
    • 대상(Audience) — 토큰 URL과 동일한 호스트입니다: https://login.salesforce.com(샌드박스라면 https://test.salesforce.com).
    • 개인 키 — Connected App에 업로드한 인증서와 짝을 이루는 RSA 개인 키입니다.

저장하기 전에 이 설정 테스트를 클릭해 연결을 확인하세요 — 실제 토큰을 발급하고 처음 몇 개 행을 미리 보여줍니다. 저장한 이후에는 언제든 저장된 연결 테스트를 사용해 개인 키를 다시 붙여넣지 않고도 재확인할 수 있습니다.

SOQL로 쿼리하기

엔드포인트의 쿼리 문자열이 곧 반환받는 데이터입니다 — 별도의 "필드 선택" UI가 없으므로, 이메일에 필요한 정확한 열을 반환하도록 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 하나당 한 행씩, 목록이나 표로 렌더링됩니다.
  • 컬렉션 연동은 KPI 스코어카드, 막대, 선, 원형 차트 블록이 직접 연동하는 대상입니다 — 합계 집계와 함께 Amount로 설정된 KPI 스코어카드의 값 필드는 병합 태그를 전혀 다룰 필요 없이 실시간 "전체 미결 파이프라인" 수치를 제공하며, StageName으로 그룹화한 막대 차트는 같은 쿼리를 단계별 파이프라인 분석으로 바꿔 줍니다.

전체 예시는 실시간 Salesforce 데이터로 구동되는 인터랙티브 이메일을 참고하세요 — 이 연결만으로 처음부터 끝까지 구축한 주간 파이프라인 다이제스트입니다.