제품 팀은 Resend 이메일 API를 어떻게 안전하게 구현해야 하나요?

제공업체 요청보다 먼저 제품 동작 정의하기

계정 인증, 영수증, 보안 알림, 수신자가 요청한 알림처럼 범위가 좁은 애플리케이션 동작에서 시작하세요. 공개 제품 엔드포인트는 Resend 페이로드가 만들어지기 전에 호출자, 테넌트, 메시지 유형, 발신자 ID, 수신자, 템플릿을 승인해야 합니다. 재사용 가능한 자격 증명을 가진 브라우저가 임의의 `from`, `to`, HTML, 제공업체 옵션을 제출하게 하지 마세요. 애플리케이션 이벤트 키, 테넌트, 템플릿 리비전, 승인된 발신자, 수신자 집합, 현재 상태를 담은 지속형 내부 발신 레코드를 만드세요. 워커는 이 레코드를 제공업체 요청으로 변환할 수 있습니다. 이 경계는 API 키와 신뢰할 수 없는 메시지 내용을 클라이언트로부터 분리하고, 중복 방지를 테스트할 수 있게 하며, 모든 비즈니스 워크플로를 다시 작성하지 않고도 제품이 제공업체를 바꿀 수 있게 해 줍니다. 내부 모델에서는 트랜잭션 메시지와 수신 동의에 의존하는 메시지를 분리해, 환경설정, 발송 제외, 사고 관련 결정이 명시적으로 유지되게 하세요.

From 주소에 사용하는 정확한 도메인 검증하기

Resend에서 직접 제어하는 도메인을 추가하고, 해당 도메인에 대해 표시되는 DNS 레코드를 게시하세요. 관련 없는 상위 ID가 이를 포함한다고 가정하지 말고, 보이는 From 주소에 실제로 사용하는 조직 도메인이나 서브도메인을 검증하세요. DNS를 변경하기 전에 기존 SPF와 DMARC 정책을 검토하고, 같은 호스트 이름에 두 번째 SPF 레코드를 만들지 마세요. 격리, 소유권, 마이그레이션 요건이 있을 때는 용도별 발신 서브도메인을 사용하세요. 대시보드에 검증됨으로 표시된 뒤에는 수신된 테스트 메시지를 확인해 보이는 From 주소, DKIM 서명 ID, Return-Path, 인증 결과, 회신 동작을 점검하세요. 제공업체의 검증은 구성된 ID가 제공업체의 설정 확인을 통과했다는 것만 증명합니다. 수신자의 동의, 수신 서버의 수락, 받은편지함 도달, 좋은 평판을 증명하지는 않습니다. 교체와 롤백이 가능하도록 DNS 소유권과 변경 이력은 제공업체 대시보드 밖에도 보존하세요.

워크로드마다 최소 권한 API 키 만들기

Resend는 접근 수준과 선택적인 도메인 제한이 있는 API 키를 문서화합니다. 발송 워커는 발송 권한만 가진 키를 사용해야 하며, 아키텍처가 허용한다면 해당 워크로드가 소유한 도메인 하나로 제한해야 합니다. 관리, 도메인, 웹훅, 계정 관리 권한은 별도의 권한으로 분리하세요. 하위 환경이 프로덕션 ID로 발송하거나 프로덕션 한도를 소모하지 못하도록 개발, 스테이징, 프로덕션마다 별도의 키를 만드세요. 각 시크릿은 관리형 시크릿 저장소에 직접 보관하고, 필요한 서버 프로세스에만 노출하고, HTTPS로 Bearer 인증에 담아 전달하세요. 키를 소스 관리, 빌드 산출물, 로그, 템플릿, 분석, 티켓, 프롬프트에 복사하지 마세요. 교체는 미리 연습해야 합니다. 범위가 동일한 대체 키를 만들고, 워커를 갱신하고, 통제된 트래픽과 이벤트 상관 관계를 검증한 뒤 이전 키를 폐기하세요. 예상치 못한 인증 및 권한 부여 실패는 만료, 폐기, 범위 변경, 시크릿 노출의 신호일 수 있으므로 알림을 설정하세요.

지속형 작업 하나에 멱등한 발송 시도 하나 만들기

Resend를 호출하기 전에 내부 발신 작업을 예약하세요. 멱등성 값은 무작위 재시도 시도가 아니라 테넌트, 작업 유형, 변경되지 않는 애플리케이션 이벤트 ID 같은 안정적인 제품 사실에서 도출하세요. 이 값을 `Idempotency-Key` 헤더에 담아 보내세요. Resend는 현재 이 키가 중복 이메일 요청을 방지하고, 24시간 후 만료되며, 최대 256자까지 가능하다고 문서화합니다. 제공업체의 이 유효 기간은 도움이 되지만 제품 수준의 완전한 중복 방지를 보장하지는 않습니다. 더 오래 걸리는 비즈니스 워크플로를 위해 내부 이벤트 키에 유일성 제약을 유지하고, 같은 작업을 가져갈 수 있는 워커를 직렬화하고, 성공한 요청이 반환한 제공업체 이메일 ID를 저장하세요. 네트워크 타임아웃으로 접수 여부가 모호하다면 작업을 알 수 없음 상태로 유지하고, 재발송하기 전에 제공업체 로그나 이벤트와 대조하세요. 전송 재시도마다 새 키를 만드는 것보다 같은 논리 작업에 안정적인 키 하나를 재사용하는 편이 더 안전합니다.

이메일 요청을 의도를 갖고 구성하고 검증하기

Resend의 이메일 발송 엔드포인트는 From 주소, 수신자, 제목, 메시지 내용을 받으며, 텍스트, HTML, React 렌더링 콘텐츠, 템플릿, Cc, Bcc, reply-to, 헤더, 첨부 파일, 태그, 예약 전달 같은 문서화된 옵션을 지원합니다. 제품에 필요한 부분 집합만 노출하세요. 주소 구문과 테넌트 소유권을 검증하고, 수신자와 첨부 파일 수는 제공업체 한도보다 낮게 제한하고, 헤더의 줄바꿈 주입을 거부하고, MIME 관련 콘텐츠는 유지 관리되는 라이브러리나 신뢰할 수 있는 제공업체 필드로 구성하세요. 자격 증명, 민감한 개인 데이터, 제한 없는 고객 입력을 태그나 헤더에 넣지 마세요. 전체 콘텐츠를 로그로 남기지 말고 템플릿 리비전과 정제된 변수를 저장하세요. 내부 어댑터는 제공업체 응답 세부 사항을 비즈니스 코드로 새어 나가게 하지 말고, 접수된 제공업체 ID나 분류된 실패 같은 좁은 결과를 반환해야 합니다. 그러면 제품 이벤트 계약을 바꾸지 않고도 제공업체별 필드 이름, SDK 버전, 요청 한도를 갱신할 수 있습니다.

재시도하기 전에 API 응답과 사용량 한도 분류하기

HTTP 응답은 워크플로의 관찰 결과 중 하나로 다루세요. 발송 성공 응답은 내부 작업과 함께 저장해야 하는 이메일 식별자를 반환하지만, 수신처의 수락이나 받은편지함 도달을 증명하지는 않습니다. 검증, 인증, 도메인, 권한, 페이로드 오류는 무작정 재시도하지 말고 바로잡으세요. Resend는 API 요청 한도를 문서화하고, 남은 용량, 초기화 시점, 재시도 지연을 설명하는 필드를 포함한 속도 제한 및 할당량 헤더를 반환합니다. 429 응답은 문서화된 간격에 지터를 더해 기다려야 합니다. 전송 실패와 재시도 가능한 서버 오류는 지수 백오프, 유한한 시도 횟수, 문서화된 유효 기간 내의 동일한 논리 멱등성 키로 재시도하세요. 클라이언트가 응답을 받지 못했더라도 제공업체는 이메일을 접수했을 수 있으므로, 모호한 실패는 대조가 필요합니다. 반복되는 실패가 도메인, 템플릿, 키, 테넌트별로 몰리면 알림을 설정하되, 자격 증명, 전체 콘텐츠, 불필요한 수신자 데이터는 운영 로그에 남기지 마세요.

이벤트를 처리하기 전에 웹훅 요청 인증하기

전용 HTTPS 웹훅 엔드포인트를 구성하고 정확한 원본 요청 본문을 보존하세요. Resend는 Svix 호환 헤더와 서명 시크릿을 통한 웹훅 서명을 문서화합니다. JSON을 파싱하거나 다시 직렬화하기 전에, 수정되지 않은 페이로드에 대해 웹훅 ID, 타임스탬프, 서명을 검증하고, 공식 검증 절차나 유지 관리되는 호환 라이브러리를 사용하세요. 유효하지 않거나 오래된 요청은 거부하고, 요청 크기에 상한을 두고, 서명 시크릿을 발송 키와 분리해 두세요. 인증한 뒤에는 이벤트를 확인 응답하기 전에 저장하거나 큐에 넣어, 프로세스가 비정상 종료되어도 전달 증거가 조용히 사라지지 않게 하세요. 전달 시스템은 웹훅을 재시도하고 중복시킬 수 있으므로, 이벤트 식별자를 중복 제거 키로 사용하고 상태 전이가 단조롭게 진행되도록 하세요. 나중에 도착했거나 중복된 이벤트가 마지막에 왔다는 이유만으로 더 많은 정보를 담은 최종 결과를 덮어써서는 안 됩니다. 검증 실패와 이벤트 지연은 운영 신호로 기록하되, 필요한 보존 기간을 넘겨 원본 메시지 내용을 저장하지 마세요.

전달을 과장하지 않고 제공업체 이벤트 모델링하기

Resend는 sent, delivered, delivery delayed, bounced, complained, failed, opened, clicked를 포함한 이름이 지정된 이메일 이벤트 유형을 공개합니다. 이러한 제공업체 이름을 원래 이벤트 유형, 제공업체 이메일 ID, 이벤트 ID, 타임스탬프, 수신자 범위, 사용 가능한 진단 데이터와 함께 내부 상태 모델에 매핑하세요. sent 이벤트는 제공업체의 진행 상황을 나타냅니다. delivered 이벤트는 Resend가 문서화한 이벤트 의미에 따라 전달을 보고하지만, 수신 시스템에서의 SMTP 성공이 수신자의 최종 폴더까지 알려 주지는 않습니다. 열람과 클릭은 전달의 증거가 아니라 참여 관찰이며, 개인정보 보호 기술이 영향을 줄 수 있습니다. 반송, 스팸 신고, 영구 실패는 다음 발송 결정 전에 수신자 안전 상태를 갱신해야 합니다. 제공업체 이벤트 이력은 추가 전용으로 유지하고, 사용자에게 보이는 상태는 명시적인 규칙으로 도출하세요. 이렇게 하면 지원을 위한 증거가 보존되고, 책임이 이미 넘어갔거나 수신자가 부정적인 신호를 보낸 뒤에 일어나는 안전하지 않은 재시도를 피할 수 있습니다.

통제된 수신자로 실패 및 복구 경로 테스트하기

비프로덕션 키, 통제된 검증 서브도메인, 팀이 소유한 메일함을 사용하세요. 텍스트와 HTML 콘텐츠, reply-to 동작, 첨부 파일 한도, 안정적인 멱등성 키, 저장된 제공업체 식별자를 테스트하세요. 같은 논리 작업을 두 번 제출해 애플리케이션과 제공업체의 제어가 의도하지 않은 중복을 만들지 않는지 확인하세요. 잘못된 페이로드, 잘못된 도메인, 폐기된 키, 권한 부족, 속도 제한, 전송 타임아웃, 반송, 스팸 신고, 전달 지연, 중복된 웹훅, 변조된 서명 본문, 오래된 웹훅 타임스탬프, 서명 시크릿 교체를 각각 시험하세요. 이벤트 수신이 확인 응답 전에 지속형으로 저장되는지, 수신자 안전 상태가 이후 작업을 차단하는지 확인하세요. 관련 없는 레코드를 삭제하지 않고 DNS 교체와 제공업체 제거를 테스트하세요. 대시보드는 발송 실패, 지연 시간, 웹훅 검증 실패, 이벤트 지연, 반송, 스팸 신고, 대조 큐를 다뤄야 합니다. 할당량, 한도, 이벤트 필드, 사용 가능한 권한은 배포된 애플리케이션 코드와 별개로 바뀔 수 있으므로, 출시 시점에 최신 Resend 문서와 계정 설정을 검토하세요.

마이그레이션 전 공개된 API 기능 비교

SendHQ는 검증된 도메인 발송, 수신 이메일, 호스팅 템플릿, 전달 이벤트, 발송 제외를 포함하는 워크스페이스 단위 이메일 API의 OpenAPI 3.1 계약을 게시합니다. 연동을 마이그레이션하기 전에 요청 본문, 인증, 멱등성, 반환 식별자, 오류 형식, 웹훅, 도메인 규칙, 발송 제외 동작을 비교하고 필드 수준 테스트로 검증하세요. 유사한 엔드포인트 이름으로 호환성을 가정하지 마세요.

자주 묻는 질문

출처

• Resend 이메일 발송 API — Resend
• Resend API 키 — Resend
• Resend 도메인 — Resend
• Resend 멱등성 키 — Resend
• Resend 사용량 한도 — Resend
• Resend 웹훅 — Resend
• Resend 웹훅 요청 검증 — Resend
• Resend 웹훅 이벤트 유형 — Resend
• RFC 5321: 단순 메일 전송 프로토콜(SMTP) — RFC Editor
• SendHQ OpenAPI 명세 — SendHQ