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

Postmark 이전에 애플리케이션 경계를 정의하세요

영수증, 인증, 요청된 알림, 보안 공지처럼 승인된 업무 이벤트에서 시작하세요. 안정적인 이벤트 키, 테넌트, 메시지 유형, 템플릿 리비전, 승인된 발신자와 수신자, 수신 동의 또는 필요성의 근거, 현재의 발송 제외 판단, 초기 상태를 포함하는 내구성 있는 발신 작업을 저장하세요. 브라우저, 모바일, 템플릿, 사용자 입력이 Postmark 서버 토큰, 임의의 From ID, 메시지 스트림, 웹훅, 제한 없는 수신자, 제공업체 메타데이터를 선택하게 해서는 안 됩니다. 모든 제공업체 호출은 서버 측 어댑터 하나 뒤에 두세요. 제품의 수신 동의 및 평판 모델에 따라 트랜잭션 트래픽과 브로드캐스트 또는 마케팅 트래픽을 분리하세요. Postmark의 API는 메시지를 전송할 뿐 테넌트 권한 부여, 수신자 동의, 업무 멱등성을 보장하지 않습니다. 내부 작업은 한 번만 확보하고, 모든 제공업체 시도를 기록하고, 제공업체 식별자는 유일한 기록 시스템으로 쓰지 말고 애플리케이션 이벤트에 연결된 증거로 보관하세요.

범위가 좁은 운영용 서버 토큰을 사용하세요

Postmark의 이메일 API는 서버 단위 API 접근을 위한 X-Postmark-Server-Token 헤더를 문서화하고 있습니다. 각 토큰은 관리형 시크릿 서비스에 저장하고, 해당 서버와 환경이 필요한 워커에만 노출하세요. 토큰을 클라이언트 코드, 소스 관리, URL, 로그, 분석 도구, 템플릿, 스크린샷, 티켓, 프롬프트, 테스트 픽스처에 절대 넣지 마세요. 폐기나 오용의 영향이 제한되도록 프로덕션과 개발, 그리고 관련 없는 제품을 분리하세요. 승인된 관리 절차로 대체 토큰을 발급하고, 워커를 업데이트하고, 통제된 메시지를 보내고, API와 이벤트 증거를 확인한 다음, 이전 토큰을 폐기하는 방식으로 교체를 미리 연습하세요. 예상치 못한 인증 오류는 자격 증명을 빠르게 재시도하라는 신호가 아니라 일시 중지 조건으로 취급하세요. 대시보드 관리는 강력한 인증과 역할로 제한하세요. 서버 토큰은 해당 서버의 Postmark API 작업을 승인할 뿐이며, 테넌트, 발신자, 수신자, 템플릿, 메시지 유형에 대한 권한은 여전히 애플리케이션이 확인해야 합니다.

정확한 발신자 ID를 검증하세요

조직이 통제하는 발신자 서명 또는 검증된 도메인을 사용하고, 모든 스트림에서 사용하는 정확한 From 주소를 확인하세요. 수신된 원본 샘플에서 화면에 표시되는 From 도메인, SMTP Return-Path, DKIM d= 도메인과 셀렉터, 답장 주소, 발송 메시지 스트림을 목록으로 정리하세요. 기존 SPF, DKIM, DMARC의 소유 관계를 검토한 후, 선택한 설정에 대해 Postmark가 현재 요구하는 DNS 레코드만 게시하세요. 이전 값과 롤백 지침을 보존하세요. 제공업체의 검증은 구성 확인이 통과했다는 증거일 뿐, 모든 애플리케이션 경로가 그 ID를 사용한다거나, DMARC가 정렬된다거나, 수신자가 동의했다거나, 메시지가 받은편지함에 도달한다는 것을 증명하지 않습니다. 테넌트별 발신자 권한은 애플리케이션에서 관리하고, 테넌트 간 From 값은 차단하세요. 서브도메인, 답장, 반송, 하위 환경, 템플릿 경로를 테스트하세요. 대시보드 표시를 녹색으로 만들겠다는 이유만으로 조직의 SPF나 DMARC 정책을 약화하지 마세요.

명시적인 POST email 요청 하나를 만드세요

Postmark는 발신자, 수신자, 제목, 텍스트 또는 HTML 본문, ReplyTo, 헤더, 태그 또는 메타데이터, 메시지 스트림, 첨부 파일, 추적 옵션을 위한 JSON 필드를 갖는 POST /email을 문서화하고 있습니다. 제품에 필요한 필드만 노출하세요. 주소를 검증하고 정규화하고, 수신자와 첨부 파일 수에 상한을 두고, 헤더 인젝션을 거부하고, 출력 컨텍스트에 맞게 템플릿 값을 이스케이프하고, 승인된 하나의 리비전에서 텍스트와 HTML을 생성하세요. 태그, 메타데이터, 헤더, 제목, 첨부 파일 이름은 제공업체의 활동 기록과 이벤트에 나타날 수 있으므로 시크릿이나 불필요한 개인 데이터를 넣지 마세요. MessageStream은 임의의 요청 입력이 아니라 신뢰할 수 있는 구성에서 선택하세요. 비즈니스 코드가 모든 Postmark 필드에 의존하지 않도록 제공업체 페이로드는 어댑터 하나에 두세요. 감사에 필요하다면 전체 메시지 본문을 로그에 남기지 말고 콘텐츠 리비전이나 개인정보를 보호하는 해시를 저장하세요.

즉각적인 응답은 제한적으로 해석하세요

Postmark의 단일 이메일 엔드포인트는 ErrorCode, Message, MessageID, SubmittedAt, 수신자 정보를 포함한 응답 필드를 문서화하고 있습니다. 정확한 HTTP 상태와 구조화된 제공업체 응답을 애플리케이션 시도와 함께 저장하세요. 성공 응답과 MessageID는 문서화된 의미에 따라 Postmark가 API 요청을 접수했음을 보여 줄 뿐, 대상 서버가 메시지를 수락했거나 받은편지함에 도달했음을 보여 주지는 않습니다. 재시도하기 전에 검증, 발신자 서명, 인증, 잘못된 페이로드, 할당량, 정책 오류를 분류하세요. Postmark가 작업을 접수했는데 클라이언트가 응답을 놓쳤을 수 있으므로 요청 타임아웃은 모호합니다. 그 시도는 알 수 없음 상태로 두고, 안전한 상관 데이터를 사용해 제공업체 활동이나 이후 이벤트를 검색하고, 재발송하기 전에 메시지 유형별 대조 규칙을 적용하세요. 정확히 한 번 전달을 약속하지 말고, HTTP 요청 하나가 실패했다는 이유만으로 새 논리 이벤트를 만들지 마세요.

제공업체 및 전송 증거를 기준으로 재시도를 설계하세요

재시도 대상이 되는 네트워크 실패, 속도 제한, 제공업체 서버 오류만 지수 백오프, 지터, 유한한 시도 횟수, 큐 보관 시간 제한으로 재시도하세요. 영구적인 요청, 발신자, 수신자, 토큰, 템플릿, 정책 오류는 재생하지 말고 바로잡으세요. 동일한 애플리케이션 이벤트 키를 유지하고 연결된 시도를 기록하세요. 큐에 있는 동안 수신자나 업무 상태가 바뀔 수 있으므로 매 재시도 직전에 발송 제외와 권한을 다시 확인하세요. 하나의 장애가 용량을 독점하지 않도록 서버, 테넌트, 메시지 스트림, 발신 도메인, 대상 코호트별로 동시성과 속도를 제한하세요. 만료된 이벤트, 폐기된 발신자 ID, 스팸 신고, 수신 거부, 영구적인 수신자 실패, 사고로 인한 일시 중지가 있으면 중단하세요. 재시도 경과 시간, 알 수 없는 결과, 응답 유형, 토큰 실패, 제공업체 지연 시간을 모니터링하세요. Postmark가 접수 후에 이미 하위 SMTP 재시도를 수행한다면, 그 전송 동작 위에 공격적인 중복 애플리케이션 루프를 만들지 마세요.

전송 및 반송 웹훅을 보호하세요

애플리케이션에 필요한 Postmark 웹훅 유형만 구성하고 HTTPS를 사용하세요. 현재 문서화된 웹훅 보안 통제를 적용하고, 엔드포인트를 예상되는 서버 또는 스트림으로 제한하고, 요청 크기와 콘텐츠 유형의 상한을 적용하고, JSON이 파싱된다는 이유만으로 메시지 식별자, 수신자, 태그, 메타데이터, 진단 정보를 신뢰하지 마세요. 성공을 반환하기 전에, 인증되었거나 달리 안전하게 수락된 이벤트를 저장하거나 큐에 넣으세요. 가능한 경우 안정적인 제공업체 이벤트 식별자로, 그렇지 않다면 수신자, 이벤트 유형, 시도가 합쳐지지 않는 보수적인 복합 키로 중복을 제거하세요. 발생 시각과 처리 시각을 따로 보존하세요. 지연, 재시도, 중복, 순서가 뒤바뀐 전달을 예상하세요. 상태를 바꾸기 전에 MessageID와 신뢰할 수 있는 메타데이터를 내부 테넌트와 작업에 연결하세요. 웹훅 자격 증명이나 URL은 API 토큰과 독립적으로 교체하고, 승인되지 않은 요청과 지연을 모니터링하고, 원본 페이로드는 운영 및 정책상의 필요가 정당화하는 기간 동안만 보관하세요.

전송, 반송, 발송 제외 상태를 모델링하세요

Postmark의 전송 및 반송 증거를 내부의 수신자 단위 모델에 매핑하되, 원래의 제공업체 유형, MessageID, 타임스탬프, 상태 또는 반송 분류, 진단 정보를 보관하세요. API 접수, Postmark 처리, 대상 서버 접수, 이후의 미전달, 메일함 폴더 위치, 참여도는 서로 다른 상태입니다. 전달됨 이벤트는 보통 최종 폴더에 대한 정보가 아니라 제공업체가 문서화한 대상 서버 관찰을 반영합니다. 일시적 실패는 상한이 있는 전송 처리를 정당화할 수 있으며, 확인된 영구적 주소 실패는 수신자 범위의 발송 제외를 만들어야 합니다. 스팸 신고와 수신 거부는 이후 작업보다 먼저 수신자 보호 상태를 갱신해야 합니다. 수동 재활성화는 권한, 사유, 감사 기록으로 보호하세요. 마이그레이션 시 수신자 보호가 사라지지 않도록 제품이 소유한 수신 동의와 발송 제외 상태를 유지하세요. 열람이나 클릭 추적은 참여도 측정 수단이며 개인정보 보호 기술의 영향을 받을 수 있으므로, 이로부터 사람이 읽었다고 추정하지 마세요.

샌드박스, 프로덕션, 실패 경로를 테스트하세요

결정적인 실패를 재현하려면 실제 고객 주소가 아니라 Postmark가 문서화한 테스트 또는 샌드박스 기능과 전용 통제 수신자를 사용하세요. 유효하거나 잘못된 토큰, 승인되지 않은 From ID, 승인되거나 차단된 수신자, 텍스트와 HTML, 유니코드, 첨부 파일, 메타데이터 최소화, 메시지 스트림, 접수 전후의 요청 타임아웃, 속도 제한 응답, 웹훅 인증, 중복 전달, 순서가 뒤바뀐 이벤트, 반송 분류, 발송 제외, 토큰 교체를 테스트하세요. 수신된 원본 헤더, DKIM 및 DMARC 정렬, Reply-To, 추적 구성, MessageID 상관 관계를 확인하세요. 하위 환경이 프로덕션 수신자에게 도달할 수 없는지 확인하세요. 발송 제외와 운영 증거에 대해 내보내기 및 마이그레이션 테스트를 실행하세요. 테넌트 간 발신자 또는 이벤트 접근, 사용할 수 없는 발송 제외 적용, 모호한 웹훅 수락, 로그에 남은 시크릿, 상한 없는 재시도, 영향을 받는 서버나 스트림을 안전하게 일시 중지하지 못하는 상황이 있으면 출시를 막으세요.

SendHQ의 활용 방식

SendHQ는 예상되는 제품 커뮤니케이션을 위한 워크스페이스 단위 이메일 API입니다. 공개 문서에서 검증된 도메인 발송, 수신 이메일, 호스팅 템플릿, 전달 이벤트, 발송 제외, 웹 대시보드를 다룹니다.

자주 묻는 질문

출처

• Postmark Email API — Postmark
• Postmark API 개요 — Postmark
• Postmark 웹훅 개요 — Postmark
• Postmark 반송 웹훅 — Postmark
• RFC 5321: 단순 메일 전송 프로토콜(SMTP) — RFC Editor