|
| 본문 표 | 레코드를 **HTML 표**로 메일 본문에 표시 | 
|
| CSV 첨부 | 레코드를 **CSV 파일**로 첨부 | 
|
「개요는 본문으로 보여주고, 상세 내역은 CSV로 전달」하는 식의 사용 방식이 가능합니다. 다만 CSV 첨부와 텍스트 첨부는 둘 중 하나만 선택할 수 있습니다.
## 요약 전달이 주된 목적
여기가 가장 중요한 포인트입니다. Email Report는 **내용 요약과 그 전달를 위한 컴포넌트**이며, **대량 데이터 출력용도가 아닙니다**.
출력에는 명확한 제한이 있습니다.
| 출력 | 제한 |
| - | - |
| 메일 본문의 표 | 최대 1,000행 |
| CSV／텍스트 첨부 | 최대 500,000행, 그리고 20MB |
즉 「문제 데이터 20건을 담당자에게 알린다」「일일 KPI를 한 줄로 보낸다」「예외 목록을 300행짜리 CSV로 전달한다」와 같은 용도에 딱 맞습니다. 반면 「전체 고객 마스터 800만 행을 매일 보낸다」와 같은 요건에는 적합하지 않습니다. 데이터셋 자체를 전달하고 싶을 때는 S3나 Snowflake 같은 파일／데이터웨어하우스 계열 데스티네이션 컴포넌트를 사용하고, Email Report는 **「처리가 끝났다는 사실」과 「요점」을 알리는 역할에 그치는 것이 정석**입니다.
## 설정해 보기
패키지 화면에서 Email Report 컴포넌트를 배치하고, 상류 컴포넌트(변환이나 집계의 출력)와 연결한 뒤 설정 화면을 엽니다. 설정은 3개의 섹션으로 나뉘어 있습니다.
### 1. Recipients & Message（수신자와 메시지）
| 항목 | 설명 |
| - | - |
| Send to | 수신자의 메일 주소. 콤마로 구분해 여러 개 지정할 수 있습니다 |
| Subject | 제목. `${variable}` 형식의 변수 참조를 사용할 수 있습니다 |
| Intro text（선택） | 표 위에 표시되는 본문 텍스트. 일반 텍스트로도 HTML로도 작성할 수 있으며, 여기에도 변수 참조를 사용할 수 있습니다 |
**제목과 본문에서 변수를 사용할 수 있다**는 점이 이 컴포넌트의 은근히 유용한 포인트입니다. 변수는 실행 시점에 해석되므로,
```
제목: [일일 점검] 적재 오류 ${_JOB_SUBMISSION_TIMESTAMP}
```
이렇게 작성해두면 실행할 때마다 날짜와 시간이 들어간 고유한 제목이 됩니다. 수신함에서 여러 메일이 하나의 스레드로 묶여버리는 문제를 피할 수 있고, 나중에 「어느 실행의 메일인지」도 추적하기 쉬워집니다.
사용할 수 있는 변수는 다음 두 가지입니다.
| 항목 | 설명 |
| - | - |
| 사용자 정의 변수 | 패키지 변수로 정의한 값. 예를 들어 `${client}`에 거래처명을 넣어두면 `제목: ${client}님을 위한 월간 리포트`처럼 끼워 넣을 수 있습니다 |
| 사전 정의 변수 | `${_JOB_ID}`（작업 식별자）, `${_JOB_SUBMISSION_TIMESTAMP}`（작업 제출 시각의 UTC・ISO-8601 형식） 등 |
사전 정의 변수 목록은 [ETL: System and Pre-Defined Variables](https://www.integrate.io/docs/etl/system-and-pre-defined-variables)를 참고하세요.
Intro text에는 「이 리포트는 자동으로 발송됩니다」「건수가 0건인 경우 이상 없음을 의미합니다」와 같은 **수신자를 위한 안내 문구**를 넣어두면 문의가 훨씬 줄어듭니다. HTML을 사용할 수 있으므로 ``로 강조하거나 사내 위키로의 링크를 걸어둘 수도 있습니다.
### 2. Email Contents（메일 내용）
여기서 앞서 본 3가지 출력 형식을 선택합니다. **최소 1개는 반드시 선택**해야 하며, 또한 선택 가능한 첨부 파일은 1종류뿐입니다.
* **Preview the rows as a table in the email body**
* 레코드를 HTML 표로 본문에 표시（최대 1,000행）
* **Attach the rows as a CSV file**
* CSV로 첨부. 파일명을 지정할 수 있습니다（기본값 `report.csv`）
* **Attach the rows as a text file**
* 탭으로 구분된 텍스트로 첨부. 파일명을 지정할 수 있습니다（기본값 `report.txt`）
파일명은 기본값 그대로 두어도 동작하지만, `report.csv`가 매일 도착하면 다운로드 폴더에서 충돌이 발생합니다. `daily_errors.csv`처럼 **용도를 알 수 있는 이름**으로 바꿔두는 것을 추천합니다.
### 3. Delivery Options（발송 옵션）
* **Fail the job if the report email cannot be sent**
* 기본값으로 활성화되어 있으며, 메일을 보낼 수 없었을 경우 작업을 실패로 처리합니다
* **When the input is too large for one email**
* Truncate and send（기본값・데이터를 샘플링해서 전송）
* Fail the job（작업 중단）에서 선택합니다
첫 번째 옵션은 기본값인 활성화 상태로 두는 것이 좋습니다. 이를 비활성화하면 메일이 도착하지 않아도 작업은 「성공」으로 종료됩니다. 알림이 도착하지 않았다는 사실을 아무도 알아채지 못하는, 가장 나쁜 상황이 될 수 있습니다. **「도착하지 않았다」를 작업 실패로 가시화한다**는 설계 사상입니다.
두 번째는 데이터가 상한을 초과했을 때의 동작입니다. 「건수가 많다는 사실 자체가 이상 신호」라면 `Fail the job`을, 「상위 수백 건만 보이면 충분」하다면 `Truncate and send`를 선택합니다.
## 실습: 「주문 실패를 알리는」 패키지
최소 구성으로 실행해 봅시다. 주문 데이터를 적재하는 과정에서 검증에 걸린 레코드를 주문 담당자에게 메일로 보내는 시나리오입니다.
### 패키지 구성
```
[Database Source: staging_orders]
│
▼
[Filter: status = 'failed']
│
▼
[Select: order_id, customer_id, error_reason, created_at]
│
▼
[Email Report Destination]
```
### 설정 내용
| 섹션 | 설정 |
| - | - |
| Send to | `data-quality@example.com, ops-lead@example.com` |
| Subject | `[Daily_report]Failed order list(${_JOB_SUBMISSION_TIMESTAMP})` |
| Intro text | `실패한 주문 처리 목록입니다. 대응 절차는 사내 위키를 확인해 주세요.
` | | Email Contents | 본문 표 ✅／CSV 첨부 ✅（파일명 `failed_orders_report.csv`） | | Delivery Options | 발송 실패 시 작업을 실패로 처리: 활성화／입력이 너무 큰 경우: `Truncate and send` | #### 받는 메일 이미지
여기서 포인트는 3단계의 **Select에서 열을 좁히고 있다**는 점입니다. Email Report는 상류에서 온 열을 그대로 출력하기 때문에, 필드 선택 과정이 없다면 내부 ID나 해시값까지 나열된 읽기 어려운 표가 그대로 도착합니다. 「메일에 담기 직전에 정리한다」. 이 한 수가 리포트의 가독성을 결정합니다.
### 발신자 주소를 자사 도메인으로 설정하기
기본 발신자는 `reports@integrate.io`입니다. 사내용 알림이라면 이대로도 문제없지만, 고객에게 제대로 전달되어야 하는 고객용 리포트라면 자사 도메인으로 보내는 것이 적절할 것입니다.
자사 도메인은 **Settings > Account Settings > Email Sender**에서 설정합니다.
| 항목 | 설명 |
| - | - |
| From address | 발신 주소 |
| From name（선택） | 수신자에게 표시되는 이름 |
| Reply-to（선택） | 회신 주소 |
참고로 **커스텀 도메인을 사용하려면 계정 승인이 필요**하며, 서전에 서포트 팀에 신청해 두세요. 아울러 해당 도메인에 SPF／DKIM 등의 발신 도메인 인증을 설정해두면 스팸 판정을 피할 수 있습니다.
## 헷갈리기 쉬운 포인트와 운영 팁
**1. 사전에 걸러내고, 메일에서 거르지 않는다.**
Email Report에는 「처음 N건만 보낸다」는 설정이 없기에 건수의 제어는 사전에 필터(Filter)나 집계(Aggregate)를 통해 처리해야 합니다. 「본문 표는 1,000행까지」라는 상한도 이 설계 사상의 표현이라고 할 수 있습니다.
**2. 「0건일 때도 보낼지」를 미리 정해둔다.**
오류 알림의 경우 0건이면 보내지 않는 편이 친절해 보일 수 있지만, 「오늘은 오지 않았다」가 「이상 없음」인지 「작업이 동작하지 않은 것」인지 구분할 수 없게 됩니다. **0건이어도 보낸다**（Intro text에 「0건＝이상 없음입니다」라고 명시해둔다）는 편이 운영상 안전합니다.
**3. 제목은 반드시 변수로 유일하게 만든다.**
매일 같은 제목의 메일은 메일 클라이언트 쪽에서 하나의 스레드로 묶여버립니다. `${_JOB_SUBMISSION_TIMESTAMP}`를 제목에 넣어두는 것만으로 이 문제를 피할 수 있습니다.
**4. 발송 실패 시 작업 실패 처리는 활성화 상태로 둔다.**
기본적으로 활성화되어 있는 이유로 「알림이 도착하지 않았다는 것」을 알아챌 수 있는 구조는 알림 자체만큼이나 중요합니다.
**5. 민감한 데이터를 본문에 싣지 않는다.**
메일은 전달（포워딩）될 수 있고, 수신자의 단말에도 남습니다. 개인정보나 결제 정보를 다루는 파이프라인에서는 메일에 「건수와 개요」만 담고, 상세 내역은 S3 등 안전한 장소에 출력한 뒤 그 링크만 Intro text에 적는 설계를 검토하세요.
## 정리
Email Report Destination은 화려한 기능은 아닙니다. 하지만 데이터 플랫폼에서 흔히 발생하는 「데이터는 나오고 있는데, 봐야하는 사람에게 전달되지 않는다」라는 마지막 간극을 메워줍니다.
* 전달・다이제스트용입니다. 대량 출력에는 사용하지 않습니다（본문 1,000행／첨부 500,000행・20MB）
* 제목과 본문에서 변수를 사용할 수 있어, 실행할 때마다 맥락이 담긴 메일을 보낼 수 있습니다
* 발송 실패를 작업 실패로 처리할 수 있어（기본값 활성화）, 알림 미도달을 알아챌 수 있습니다
* 가독성은 사전 처리로 Filter/Aggregate/Select에서 결정됩니다
우선은 기존 패키지의 끝단에 하나 추가해보는 것부터 시작해보세요. 소요 시간은 10분도 걸리지 않습니다.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.