가이드 · sendgrid api

제품 팀은 SendGrid API를 어떻게 안전하게 구현해야 하나요?

인증된 발신 도메인과 Mail Send 권한으로만 제한한 API 키를 사용하여, SendGrid API를 서버 측 메일 서비스 뒤에서 구현하세요. `POST /v3/mail/send`를 호출하기 전에 모든 메시지를 검증하고, 자체 발송 기록을 저장하고, 응답의 `X-Message-ID`를 기록하세요. 서명된 Event Webhook 페이로드는 원본 바이트 기준으로 처리하고, 이벤트 중복을 제거하고, 반송, 스팸 신고, 수신 거부를 존중하세요. `202 Accepted`, 수신 서버 전달, 받은편지함 도달은 별개의 상태로 취급하고, 일시적인 실패에 한해서만 상한이 있는 재시도를 적용하세요.

범위가 좁고 정당한 발송 작업을 정의하세요

SendGrid의 v3 Mail Send API는 범용 사용자 메일함이 아니라 발신 이메일을 위한 제공업체 엔드포인트입니다. 신뢰할 수 있는 애플리케이션 서비스나 큐 워커 뒤에 두고, 계정 인증, 영수증, 보안 공지, 요청된 알림처럼 어떤 제품 이벤트가 메시지를 만들 수 있는지 정의하세요. 제공업체 키를 브라우저, 모바일 클라이언트, 템플릿, 프롬프트, 로그에 노출하지 마세요. 수신자의 기대, 환경설정 처리, 평판을 독립적으로 운영할 수 있도록 데이터 모델 수준에서 트랜잭션 메시지와 수신 동의에 따르는 캠페인을 분리하세요. 구현하기 전에 발신 도메인의 소유자, 템플릿 승인자, 외부로 발송할 수 있는 환경, 개발 환경에서 허용되는 수신자를 정하세요. 이 범위가 API 키 권한, 도메인 설정, 감사 기록, 알림, 사고 대응의 경계가 됩니다. 또한 제품 코드가 애플리케이션 곳곳에서 임의의 SendGrid 요청을 구성하는 대신 승인된 이메일 작업을 요청하게 되므로 제공업체 마이그레이션도 가능해집니다.

전용 발신 도메인을 인증하세요

직접 관리하는 도메인 또는 용도별 서브도메인에 대해 SendGrid Domain Authentication을 구성하고, 해당 ID에 대해 생성된 DNS 레코드를 그대로 게시한 뒤 SendGrid에서 검증하세요. 제공업체 문서에 따르면 서브도메인은 인증된 상위 ID를 상속하지 않으므로, From 주소에 실제로 사용하는 도메인을 검증하세요. DNS를 변경하기 전에 기존 SPF 및 DMARC 레코드를 검토하고, 같은 호스트 이름에 두 번째 SPF 정책을 만들거나 소유자의 동의 없이 조직의 기존 DMARC 정책을 교체하지 마세요. 대상과 위험이 다른 경우 트랜잭션 트래픽과 프로모션 트래픽은 의도적으로 선택한 ID에 두세요. 수신된 테스트 메시지에서 화면에 표시되는 From 주소, Return-Path, DKIM 서명 도메인, 답장 경로, 링크 브랜딩 동작을 확인하세요. 인증은 승인된 ID와 정렬 신호를 확립하지만 수신 시스템의 최종 폴더를 결정하지는 않습니다. DNS 검증이 성공한 뒤에도 반송, 스팸 신고, 수신자의 기대, 콘텐츠를 계속 모니터링하세요.

환경마다 최소 권한 API 키를 발급하세요

워크로드에 필요한 권한만 가진 Custom Access API 키를 만드세요. 발송 워커라면 보통 Mail Send 접근 권한이면 됩니다. 일상적인 발신자에게 템플릿, 발송 제외, 팀원, 통계, IP 구성, 계정 관리에 대한 Full Access를 주지 마세요. 개발, 스테이징, 프로덕션에 각각 별도의 키를 사용하고, 소유 서비스와 교체 목적을 알 수 있는 이름을 붙이세요. SendGrid는 새 키를 한 번만 표시하므로 환경의 시크릿 관리자에 바로 넣고, 소스 관리나 공유 문서에는 절대 복사하지 마세요. 런타임에는 시크릿 기반 구성에서 읽어 HTTPS 위의 `Authorization: Bearer` 헤더로만 전달하세요. 키 교체를 운영 절차로 테스트하세요. 동등하게 좁은 권한의 대체 키를 만들고, 대체 키를 배포하고, 통제된 트래픽이 성공하는지 확인한 뒤, 이전 키를 폐기합니다. 키 누락, 폐기된 자격 증명, 권한 불일치, 안전하지 않은 구성 변경을 나타낼 수 있으므로 예상치 못한 401 또는 403 응답에 대해 알림을 설정하세요.

각 Mail Send 요청을 구성하고 기록하세요

SendGrid에 연락하기 전에 내부 발신 기록을 하나 만드세요. 안정적인 애플리케이션 이벤트 키, 테넌트, 발신자 ID, 승인된 수신자, 메시지 유형, 템플릿 버전, 상태를 부여하세요. 이 기록에서 `personalizations`, `from`, `subject`와, 지원되는 콘텐츠 파트 하나 이상 또는 승인된 동적 템플릿을 사용하여 제공업체 페이로드를 구성하세요. 네트워크 호출 전에 주소 구문, 수신자 수, 첨부 파일 크기, 템플릿 데이터, 사용자 정의 헤더를 검증하세요. SendGrid의 최신 Mail Send 개요는 첨부 파일을 포함한 전체 요청 크기를 30 MB 미만으로, To, Cc, Bcc를 합친 전체 수신자를 1,000명 이하로 제한합니다. 더 작고 목적이 분명한 요청이 감사하고 복구하기가 더 쉽습니다. `202 Accepted` 응답을 받으면 `X-Message-ID` 헤더를 기록해 발신 기록에 연결하세요. 카테고리나 고유 인수(unique arguments)에는 개인 데이터를 넣지 마세요. SendGrid는 이 값들이 보관될 수 있고 메시지 콘텐츠에 기대되는 보호 밖에서 조회될 수 있다고 경고합니다.

Event Webhook을 검증하고 처리하세요

원본 요청 본문을 유지할 수 있는 HTTPS 엔드포인트에 SendGrid Event Webhook을 구성하세요. 암호화 서명, OAuth 2.0, 또는 둘 다를 활성화하세요. 서명된 전달의 경우, JSON을 파싱하기 전에 정확한 원본 바이트를 기준으로 타임스탬프와 `X-Twilio-Email-Event-Webhook-Signature`를 검증하세요. Twilio는 페이로드를 다시 직렬화하면 바이트가 바뀌어 검증이 무효화될 수 있다고 경고합니다. 인증되지 않은 입력은 거부하고, 합리적인 요청 크기 제한을 적용하고, 팀이 선택한 타임스탬프 정책에 따라 재생을 방지하세요. 검증 후에는 성공을 반환하기 전에 이벤트 배치를 큐에 넣거나 내구성 있게 저장하세요. `sg_event_id`로 중복을 제거한 다음, `sg_message_id`, 저장된 `X-Message-ID`, 민감하지 않은 내부 상관 값을 연결하세요. 지연된 processed 이벤트가 이후의 delivered 또는 bounce 결과를 덮어쓰지 않도록 상태 전이를 단조롭게 만드세요. 문제 해결을 위해 원본 제공업체 이벤트는 접근이 제한된 저장소에 보관하되, 주소, 응답 텍스트, 참여도 데이터의 보관은 제품과 정책이 실제로 요구하는 수준으로 최소화하세요.

접수, 전달, 도달을 정확하게 모델링하세요

SendGrid의 HTTP `202 Accepted`는 요청이 접수되어 처리를 위해 큐에 들어갔다는 뜻입니다. 대상 서버가 메시지를 수락했다는 뜻은 아닙니다. `processed` 웹훅 이벤트는 SendGrid가 메시지를 접수했고 전송을 시도할 수 있다는 뜻입니다. `delivered` 이벤트는 수신 메일 서버가 이를 수락했다고 SendGrid가 보고한다는 뜻이며, 흔히 SMTP 응답이 함께 옵니다. 그래도 받은편지함 도달이 입증되는 것은 아닙니다. 수신 시스템이 수락한 메일을 받은편지함 탭, 격리, 스팸함 또는 다른 위치로 분류할 수 있기 때문입니다. 저장소와 사용자 인터페이스에서 요청됨, 제공업체 접수됨, 처리됨, 지연됨, 수신 서버 수락됨, 반송됨, 드롭됨, 스팸 신고됨, 발송 제외됨 상태를 구분해서 유지하세요. 오류가 아닌 모든 HTTP 응답을 “전달됨”으로 바꾸지 마세요. 열람 같은 참여도 신호도 전달의 증거가 아니며 개인정보 보호 기능의 영향을 받을 수 있습니다. 정확한 상태 이름은 지원 조사, 재시도, 전달성 판단을 더 안전하게 만듭니다.

재시도하기 전에 실패를 분류하세요

202가 아닌 모든 응답을 재시도하지 말고 유형별로 제공업체 오류를 처리하세요. 400은 보통 페이로드, 발신자, 템플릿 데이터, 예약된 헤더를 바로잡아야 합니다. 401은 인증 문제를 가리키고, 403은 권한 부족이나 계정 정책을 나타낼 수 있으며, 413은 메시지 크기를 줄여야 합니다. SendGrid는 엔드포인트별 속도 제한 헤더를 문서화하고 있으며 갱신 주기 허용량이 소진되면 429를 반환하므로, 초기화 시각까지 지연하고 동기화된 재시도를 만들지 않도록 지터를 추가하세요. 5xx와 전송 실패는 지수 백오프, 유한한 시도 횟수, 운영 알림과 함께 재시도하세요. 모호한 타임아웃은 특별한 주의가 필요합니다. 클라이언트가 응답을 놓쳤더라도 제공업체는 요청을 접수했을 수 있습니다. 발신 기록을 알 수 없음 상태로 두고, 상관된 이벤트를 찾아보고, 재발송하기 전에 의도적인 대조 규칙을 요구하세요. 제공업체 API가 있다고 해서 제품 수준의 중복 방지가 불필요해지지는 않습니다. 알려진 영구 반송, 잘못된 수신자, 수신 거부, 스팸 신고 대상은 일시적인 인프라 오류처럼 재시도하지 마세요.

발송 제외와 수신자의 선택을 존중하세요

반송, 드롭, 스팸 신고, 수신 거부, 그룹 수신 거부 이벤트를 수신자 보호 모델로 수집하세요. SendGrid는 메시지 유형별로 전역 발송 제외와 수신 거부 그룹을 지원합니다. 프로모션 또는 선택 메시지마다 올바른 그룹을 연결하고, 이해하기 쉬운 환경설정 경로를 제공하고, 해당 발송 제외가 적용되면 발송을 중단하세요. 발송 제외 우회 옵션을 일상적인 전달 기법으로 사용하지 마세요. 제품의 핵심 메시지에는 별도로 문서화된 법적 및 운영 정책이 필요할 수 있지만, 그 정책이 개인의 프로모션 관련 선택이나 제공업체의 평판 보호 장치를 조용히 무시해서는 안 됩니다. 발송 제외를 해제하는 지원 도구는 강력한 권한 부여, 눈에 보이는 사유, 감사 추적으로 보호하세요. 영구적인 전송 실패와 일시적인 전송 실패를 따로 추적하고, 다음 발송 전에 모든 수동 재활성화를 검토하세요. 이러한 통제는 수신자를 보호하고 이미 트래픽을 거부하거나 수락하지 않은 대상으로 반복해서 시도하는 일을 줄입니다. 또한 트랜잭션 발송이 안전하지 않은 캠페인 동작을 물려받지 않도록 합니다.

프로덕션 트래픽 전에 전체 수명 주기를 테스트하세요

프로덕션이 아닌 SendGrid 키와 통제된 인증 서브도메인으로 시작하세요. DNS를 검증한 다음, 팀이 소유한 받은편지함으로 일반 텍스트와 HTML 버전을 발송하세요. `202` 응답과 `X-Message-ID`를 확인하고, 서명된 웹훅 이벤트가 로컬 발신 기록과 연결되는지 검증하세요. 실제 고객 주소를 사용하지 않고, 잘못된 페이로드, 폐기된 키, 권한 누락, 크기 초과 첨부 파일, 속도 제한, 지연, 반송, 드롭, 중복 이벤트 경로를 시험하세요. 웹훅 검증이 변조된 본문을 거부하는지, 핸들러가 내구성 있게 저장한 후에만 확인 응답을 보내는지 확인하세요. 키 교체, 템플릿 롤백, 발송 제외 적용, 모호한 클라이언트 타임아웃을 테스트하세요. 요청 실패, 이벤트 지연, 지연 전송, 반송, 스팸 신고, 웹훅 서명 실패에 대한 대시보드를 추가하되, 테넌트와 메시지 식별자는 포함하고 자격 증명이나 전체 콘텐츠는 포함하지 마세요. 마지막으로, 요금제 혜택, 리전별 기능, 할당량, 제공업체 정책은 애플리케이션 코드와 별개로 바뀔 수 있으므로 출시 시점에 SendGrid의 최신 문서와 계정 한도를 검토하세요.

제공업체별 종속성 비교

팀이 SendGrid 전용 요청 필드, 템플릿, 계정 제어, 웹훅 형식, 발송 제외, 운영 소유권에 의도적으로 의존할 때 직접 SendGrid 연동이 적절합니다. SendHQ의 공개 문서는 검증된 도메인 발송, 수신 이메일, 호스팅 템플릿, 전달 이벤트, 발송 제외, 웹 대시보드를 갖춘 워크스페이스 단위 이메일 API를 설명합니다. 마이그레이션 전에 두 제공업체의 페이로드, 이벤트, ID 제어, 발송 제외, 지역 요구 사항, 저장된 제공업체 식별자를 검토하세요.

자주 묻는 질문

SendGrid의 202 Accepted는 이메일이 전달되었다는 뜻인가요?

아니요. SendGrid가 처리를 위해 API 요청을 접수했다는 뜻입니다. 수신 서버가 메시지를 수락했는지는 Event Webhook의 전송 이벤트로 확인하고, 받은편지함 도달은 API 응답으로 입증되지 않는 별개의 결과로 유지하세요.

SendGrid 발송 키에는 어떤 권한을 부여해야 하나요?

워커에 필요한 Mail Send 기능으로만 제한한 Custom Access 키를 사용하세요. 일상적인 발송에는 Full Access를 피하고, 개발, 스테이징, 프로덕션, 관리, 그리고 권한이 크게 다른 그 밖의 워크로드에는 각각 시크릿 관리되는 별도의 키를 사용하세요.

SendGrid Event Webhook 서명은 어떻게 검증해야 하나요?

정확한 원본 HTTP 본문을 유지하고, Twilio 서명과 타임스탬프 헤더를 읽어, JSON 파싱이나 재직렬화 전에 검증하세요. 재생 방지를 적용하고, 검증에 실패하면 거부하고, 전달을 확인 응답하기 전에 이벤트 배치를 내구성 있게 저장하거나 큐에 넣으세요.

제품은 실패한 모든 Mail Send 요청을 재시도해야 하나요?

아니요. 페이로드, 인증, 권한 부여, 크기, 영구적인 수신자 오류는 재시도하지 말고 수정하세요. 429 응답은 문서화된 초기화 시각까지 지연하고, 일시적인 네트워크 및 5xx 실패는 상한이 있는 백오프로 재시도하고, 모호한 타임아웃은 재발송 전에 대조하세요.

트랜잭션 이메일에는 SendGrid의 발송 제외를 우회해도 되나요?

SendGrid는 우회 옵션을 제공하지만, 제품이 이를 일상적으로 사용해서는 안 됩니다. 메시지 유형을 분리하고, 해당하는 수신 거부 또는 발송 제외를 존중하고, 예외적인 재활성화나 정책에 따른 발송 결정에는 문서화된 권한 부여와 감사 기록을 요구하세요.

팀은 SendGrid와 SendHQ를 비교하기 전에 무엇을 평가해야 하나요?

마이그레이션을 계획하기 전에 제공업체의 페이로드, 이벤트, ID 제어, 발송 제외, 지역 요구 사항, 저장된 제공업체 식별자를 비교하세요.

출처

더 알아보기

제품 팀을 위한 이메일 API 구현 가이드검증된 도메인, 큐 기반 발송, 안정적인 식별자, 통제된 재시도, 전송 이벤트, 발송 제외 처리, 테넌트 격리를 갖춘 안전한 이메일 API 연동을 설계합니다.