데이터 소스 및 병합 태그

병합 태그를 사용하면 실제 데이터로 모든 이메일을 개인화할 수 있습니다. 텍스트 블록 어디에나 {{field}}를 입력하면 — 예: Hi {{first_name}}, your {{plan}} renews soon — 각 수신자에게 자신의 값이 표시됩니다. 하나의 프로젝트는 여러 데이터 소스를 동시에 연결할 수 있습니다. 각 소스에는 짧은 별칭이 부여되며, 오디언스가 아닌 소스의 필드는 {{alias.field}} 형태로 작성합니다(예: {{products.name}}).

데이터 소스 유형

데이터 소스는 대시보드의 데이터 소스 섹션에서 관리합니다(연락처 목록은 연락처에 있습니다). 유형은 두 가지입니다.

호스팅 테이블

MailInApp에 저장된 테이블입니다. 대시보드에서 열을 정의하고 행을 추가하면 모든 열이 병합 필드가 됩니다. 현재 데이터가 스프레드시트에 있는 경우에 가장 적합합니다. 연락처 목록은 email 열이 보장되는 호스팅 테이블입니다.

API 연결

JSON을 반환하는 자체 HTTP 엔드포인트를 MailInApp에 지정하세요. 행은 서버 사이드에서 가져옵니다 — 즉 저희 서버에서 가져오며, 수신자의 받은편지함이나 방문자의 브라우저에서 가져오는 일은 없습니다.

연결을 인증하는 방법은 세 가지이며, 설정할 때 인증 드롭다운에서 선택합니다.

• 정적 헤더 — 고정된 값을 가진 요청 헤더(예: Authorization 헤더)를 추가합니다. 가장 단순한 방식이며, 토큰이 만료될 수 있다는 개념이 생기기 전까지 유일하게 의미 있었던 방식입니다.
• OAuth2 클라이언트 자격 증명(Client Credentials) — 토큰 URL과 클라이언트 ID, 시크릿입니다. MailInApp이 서버 사이드에서 이를 액세스 토큰으로 교환하고 캐시하며, 만료되기 전에 자동으로 갱신합니다 — 대부분의 API 키·시크릿 기반 엔터프라이즈 연동에서 흔히 쓰이는 방식입니다.
• OAuth2 JWT Bearer — 토큰 URL, 발급자(issuer), 주체(subject), 대상(audience), RSA 개인 키(PEM)입니다. MailInApp이 매번 새로운 JWT 어설션에 서명해 액세스 토큰으로 교환하며, 대화형 로그인도 관리해야 할 리프레시 토큰도 필요 없습니다 — Salesforce의 서버 간 연동이 인증하는 방식이 바로 이것이며(Salesforce 연동 가이드 참고), Google 서비스 계정이나 이 흐름을 지원하는 다른 IdP에서도 동일하게 동작합니다.

어떤 방식을 선택하든, 발급된 베어러 토큰은 자동으로 Authorization 헤더로 주입됩니다 — 추가로 설정한 헤더가 있다면 이와 함께 병합되어 그대로 전송됩니다(단, 거기서 이름이 정확히 Authorization인 헤더는 무시됩니다. 발급된 토큰이 항상 우선하기 때문입니다). 헤더 값, 클라이언트 시크릿, 개인 키를 비롯한 모든 자격 증명 필드는 다음 규칙을 동일하게 따릅니다.

• 서버 사이드에만 저장되고,
• 브라우저로 전송되지 않으며,
• 저장한 이후에는 모든 API 응답에서 마스킹됩니다.

시크릿이 마스킹되어 표시되는 연결을 편집하면서 이 설정 테스트를 클릭하려면 먼저 실제 값을 다시 입력해야 합니다. 반면 저장된 연결 테스트는 저장된 그대로의 자격 증명으로 확인을 수행하며, 그 값을 브라우저로 다시 전송하는 일은 없습니다.

소스 연결하기: 데이터 패널

스튜디오의 데이터 패널은 프로젝트가 사용할 소스를 지정하는 곳입니다. **+ 데이터 소스 추가…**로 소스를 하나 연결하며(프로젝트당 최대 10개), 각 연결은 세 부분으로 구성됩니다.

• 별칭 — 병합 태그가 사용하는 짧은 handle로, 소문자, 숫자, 밑줄로 구성되며 문자로 시작해야 합니다(예: contacts, products, open_invoices). 별칭 이름을 바꾸면 해당 별칭에 연동된 반복 블록도 자동으로 업데이트됩니다.
• 소스 — 그 뒤에 있는 호스팅 테이블, 연락처 목록 또는 API 연결입니다.
• 역할 — 이메일이 이를 어떻게 사용하는지입니다.
  • 오디언스 — 이메일이 발송되는 연락처 목록입니다. 프로젝트당 최대 하나이며 반드시 연락처 목록이어야 합니다. 이 소스의 필드는 별칭 없는(bare) 태그 — {{first_name}}, {{email}} — 로 사용되며, 발송 시점에 각 수신자 본인의 행에서 해석됩니다. 오디언스는 "다음으로 미리보기" 선택기와 수신자별 응답 귀속(attribution)도 함께 좌우합니다.
  • 병합 필드 — 별칭 아래에서 읽을 수 있는 필드로, {{alias.field}} 형태이며 이메일이 렌더링될 때 소스의 첫 번째 행에서 해석됩니다. 수신자별 데이터가 아니라 추천 상품이나 이번 주 통계 같은 공유 콘텐츠에 사용하세요.
  • 반복 행 — 해당 별칭에 연동된 반복 블록에 공급되는 행입니다. 반복 밖에서는 병합 필드를 제공하지 않습니다. 동일한 collection 역할은 KPI/막대/선/원형 차트 블록에도 데이터를 공급합니다 — 차트를 실제 데이터에 연동하기 참고.

연결된 모든 소스는 필드를 클릭 가능한 칩으로 나열합니다 — 하나를 클릭하면 정확한 병합 태그가 복사되어 어떤 텍스트 속성에도 붙여넣을 수 있습니다. 표시 조건 편집기의 필드 드롭다운도 동일한 방식으로 그룹화됩니다: 수신자(오디언스) 필드에 이어 병합 소스별로 하나씩 그룹이 나타납니다.

내장 태그

데이터 소스가 아니라 플랫폼 자체에서 제공하는 태그가 몇 가지 있습니다 — 스튜디오 좌측 패널의 변수 패널에 여러분이 정의한 변수와 함께 나열되며, 클릭하면 태그가 복사됩니다.

• {{recipient_email}} — 이메일이 발송되는 주소입니다.
• {{today}} / {{now}} — 이메일이 열린 날짜(또는 날짜와 시간)입니다.
• {{unsubscribe_url}} — 수신자별 원클릭 수신 거부 링크입니다. 푸터 프리셋에 이미 포함되어 있습니다 — 연락처로 발송하기 참고.

수신자별 1회용 스토어 할인 코드는 병합 태그가 아닙니다 — 대신 이커머스 할인 블록(Shopify/WooCommerce에 연결된 오디언스에서만 사용 가능)을 이메일에 넣으면 자체 코드를 자동으로 발급하고 표시합니다. 할인 오퍼를 참고하세요.

내장 태그는 실제 발송(수동, 예약 발송 또는 "백필" 형태의 테스트 발송)에서만 해석됩니다 — 스튜디오 미리보기와 캔버스에서는 샘플 값이 없는 다른 필드와 마찬가지로 비어 있거나 플레이스홀더로 표시됩니다.

반복 콘텐츠

반복 블록은 연동한 소스의 각 행마다 자식 요소를 한 번씩 렌더링합니다 — 상품 그리드, 아티클 다이제스트, 미결제 인보이스 목록 등입니다. 인스펙터에서 별칭으로 소스를 선택하세요. 반복 안에서는 태그가 각 반복 항목 자신의 행을 기준으로 해석됩니다.

실제 데이터로 미리보기

스튜디오의 미리보기 데이터 선택기는 오디언스 목록의 임의 행으로 캔버스를 렌더링하므로, 발송 전에 {{first_name}}이 {{first_name}}이 아니라 실제로 Amina라고 표시되는지 확인할 수 있습니다. 다른 소스의 필드에도 미리보기 값을 지정할 수 있습니다.

알아두면 좋은 점

• 수신자에게 없는 필드는 빈 문자열로 렌더링됩니다 — 값이 비어 있어도 자연스럽게 읽히도록 디자인하세요.
• 호스팅 페이지(라이브 뷰, 호스팅 폼)는 렌더링 시점에 수신자별로 병합 태그를 해석하므로, 수신자가 받은편지함을 벗어나도 개인화가 유지됩니다.
• 다중 소스 지원 이전에 만들어진 프로젝트도 변경 없이 그대로 동작합니다: 기존에 연결되어 있던 단일 소스가 데이터 패널에 자동으로 표시되며, 별칭 없는 {{field}} 태그는 항상 오디언스를 기준으로 해석됩니다.