개요#
파일 전송 작업의 상태 변화를 이메일로 전달받으려면 Twilio SendGrid 알림을 연동할 수 있습니다.
연동을 완료하면 전송이 시작(Started), 완료(Completed), 실패(Failed) 되는 등 지정한 이벤트가 발생할 때마다 지정한 수신 이메일로 알림 메일이 자동으로 전송됩니다.
전체 과정은 ① API Key 발급 → ② 발신자 이메일 인증 → ③ 제품에서 알림 설정 순으로 진행됩니다.
준비 사항#
시작하기 전에 다음 사항을 확인하세요.
| 항목 | 설명 |
|---|---|
| SendGrid 계정 | API Key를 발급하고 발신자를 인증할 수 있는 SendGrid 계정이 필요합니다. |
| 발신 이메일/도메인 | 발신에 사용할 이메일 또는 도메인을 SendGrid에서 인증합니다. |
| 네트워크 | 제품이 설치된 환경에서 api.sendgrid.com(443)으로의 외부 HTTPS 통신이 허용되어야 합니다. |
API Key 발급#
SendGrid로 메일을 보내려면 메일 발송 권한이 있는 API Key를 발급받습니다.
Step 1. API Keys 열기#
SendGrid 콘솔에서 Settings → API Keys로 이동한 후 Create API Key를 클릭합니다.
Step 2. 권한 설정 및 생성#
API Key 이름을 입력하고 권한을 설정합니다.
최소 권한 원칙에 따라 Restricted Access에서 Mail Send 권한만 부여하는 것을 권장합니다.
(Full Access 권한으로도 메일 발송은 가능합니다.)
설정을 완료한 후 Create & View를 클릭하여 API Key를 생성합니다.
Step 3. API Key 복사#
SG.로 시작하는 API Key를 복사합니다.
ℹ️ API Key는 생성 화면에서만 확인할 수 있으므로 안전한 위치에 보관해야 합니다. 이 API Key는 비밀번호와 같은 정보입니다. 값을 알고 있는 사람은 부여된 권한으로 계정의 메일을 발송할 수 있으므로 공개 저장소나 외부 문서에 노출되지 않도록 주의합니다. API Key가 유출된 경우에는 SendGrid에서 기존 키를 삭제한 후 새로 발급합니다.
확인 사항#
- ✔ Mail Send 권한이 있는 API Key를 발급했습니다.
- ✔ API Key를 안전하게 복사하여 보관했습니다.
발신자 이메일 인증#
SendGrid에서는 인증된 발신자만 메일을 보낼 수 있습니다.
인증되지 않은 발신자를 사용할 경우 메일 발송이 거부(403)되므로 발신 이메일 또는 도메인을 먼저 인증해야 합니다.
Step 1. Sender Authentication 열기#
SendGrid 콘솔에서 Settings → Sender Authentication으로 이동합니다.
Step 2. 발신자 인증#
다음 두 가지 방법 중 하나를 사용하여 발신자를 인증합니다.
- Single Sender Verification - Create New Sender를 선택한 후 이름, 이메일 및 주소 정보를 입력합니다. 인증 메일이 발송되며 메일의 링크를 클릭하면 해당 이메일 주소를 사용할 수 있습니다. (개발 및 테스트 환경에 적합)
- Domain Authentication (권장) - 안내되는 CNAME DNS 레코드를 도메인에 추가하여 인증합니다. 인증된 도메인의 모든 이메일 주소를 사용할 수 있으며 스팸 판정을 줄일 수 있어 운영 환경에 적합합니다.
확인 사항#
- ✔ 발신 이메일 또는 도메인이 인증되었습니다.
Twilio SendGrid 알림 설정#
발급받은 API Key와 인증된 이메일 정보를 제품의 알림 설정에 입력합니다.
Notifications 설정 창을 열면 아래와 같은 화면이 표시됩니다.
Step 1. API Key 입력#
API Key 항목에 API Key 발급에서 복사한 API Key를 입력합니다.
Step 2. Sender Email 입력#
Sender Email 항목에 발신자 이메일 인증에서 인증한 발신 이메일을 입력합니다.
Step 3. Recipient Email 입력#
Recipient Email 항목에 알림을 받을 수신 이메일을 입력합니다.
Step 4. 알림 이벤트 선택#
Events 항목에서 알림을 받을 이벤트를 선택합니다.
여러 개를 선택할 수 있으며 선택한 이벤트가 발생할 때만 이메일이 전송됩니다.
| 이벤트 | 발생 시점 |
|---|---|
| Started | 전송 작업이 시작되었을 때 |
| Completed | 전송이 정상적으로 완료되었을 때 |
| Paused | 전송이 일시 중지되었을 때 |
| Resumed | 일시 중지된 전송이 다시 시작되었을 때 |
| Recovered | 중단 또는 오류 후 전송이 자동 복구되어 재개되었을 때 |
| Canceled | 사용자가 전송을 취소했을 때 |
| Failed | 전송이 실패했을 때 |
| Skipped | 특정 파일이 건너뛰어졌을 때 (예: 이미 존재하는 파일 또는 필터 조건에 해당하는 경우) |
Step 5. 설정 저장#
입력을 완료한 후 Add를 클릭하여 연동을 저장합니다.
확인 사항#
- ✔ API Key가 입력되었습니다.
- ✔ 발신 이메일과 수신 이메일이 입력되었습니다.
- ✔ 알림받을 이벤트가 선택되었습니다.
연동 확인#
설정이 정상적으로 동작하는지 확인합니다.
Step 1. 테스트 이벤트 발생#
실제 전송 작업을 실행하거나 선택한 이벤트 중 하나를 발생시킵니다.
Step 2. 수신 메일함 확인#
지정한 수신 이메일로 알림 메일이 도착했는지 확인합니다.
확인 사항#
- ✔ 수신 이메일로 알림 메일이 도착했습니다.
- ✔ 발생한 이벤트가 정확하게 전달되었습니다.
설정 완료#
설정을 저장하면 연동이 적용됩니다.
이후 선택한 이벤트가 발생할 때마다 지정한 수신 이메일로 알림 메일이 자동으로 전송됩니다.
문제 해결 (Troubleshooting)#
메일이 도착하지 않는 경우 아래 항목을 확인하세요.
| 문제 | 확인 사항 |
|---|---|
| 메일이 발송되지 않음 | API Key와 발신 이메일 및 수신 이메일이 정확하게 입력되었는지 확인합니다. |
| 인증 오류(401)가 발생함 | API Key가 올바른지, 삭제되거나 재발급되지 않았는지 확인합니다. |
| 발송이 거부됨(403) | 발신 이메일이 인증(Single Sender Verification 또는 Domain Authentication)되었는지, API Key에 Mail Send 권한이 있는지 확인합니다. |
| 메일이 스팸함으로 전달됨 | Domain Authentication이 완료되었는지 확인합니다. |
| 폐쇄망에서 연동 실패 | api.sendgrid.com(443)으로의 아웃바운드 HTTPS 통신이 방화벽 또는 프록시에서 허용되어 있는지 확인합니다. |