멱등성 키(Idempotency Key)란? 이메일 중복 발송 방지

동작 원리

클라이언트가 멱등성 키와 함께 요청을 보내면 서버는 키와 그 결과 응답을 캐시에 저장합니다. 같은 키로 이후 요청이 도착하면 서버는 실행 로직을 건너뛰고 캐시된 응답만 반환합니다. 이 메커니즘은 네트워크 타임아웃 때문에 클라이언트가 요청이 서버에 도달했는지 알 수 없는 분산 시스템에서 매우 중요합니다.

발신자에게 중요한 이유

트랜잭션 이메일에서 같은 메시지를 두 번 보내면 사용자 경험이 나빠지고 스팸 신고가 늘어날 수 있습니다. 멱등성 키를 사용하면 개발자는 수신자에게 이메일이 중복 발송될 위험 없이 실패한 네트워크 호출에 공격적인 재시도 로직을 구현할 수 있습니다. 이를 통해 전달 파이프라인 전반의 안정성과 일관성이 보장됩니다.

운영상 고려 사항

키는 충돌을 피하기 위해 UUID나 엔트로피가 높은 임의 문자열로 생성해야 합니다. 서버는 보통 24시간 후에 이 키를 만료시킵니다. 개발자는 키가 메시지의 구체적인 의도와 연결되도록 해야 합니다. 같은 키를 유지한 채 이메일 본문이나 수신자를 바꾸면 캐시된 성공 응답이 아니라 오류가 반환되어야 합니다.

구현 예시

한 SaaS 애플리케이션이 비밀번호 재설정 이메일용 고유 키를 생성합니다. 앱이 이메일 API를 호출했지만 응답을 받기 전에 연결이 끊어집니다. 앱은 같은 키로 요청을 재시도합니다. API는 이미 존재하는 키임을 확인하고 사용자에게 두 번째 이메일을 보내지 않은 채 200 OK를 반환합니다. SendHQ 무료 도구는 개발자가 이메일 인프라를 효율적으로 관리하는 데 도움이 됩니다.

오류 처리

요청이 수정되었는데 기존 멱등성 키로 전송되면 서버는 충돌 오류를 반환해야 합니다. 이렇게 하면 서로 다른 메시지에 키를 실수로 재사용하는 것을 방지합니다. 올바른 처리 방법은 이러한 충돌을 포착해 업데이트된 요청 페이로드용으로 새 키를 생성하는 것입니다.

팀에서 자주 묻는 질문

1차 출처

• SendGrid 문서 — Twilio SendGrid
• Postmark 개발자 문서 — Postmark