Postmark API 개요

Postmark API 개요

Postmark는 거래 이메일(transactional email) 전송에 특화된 이메일 API 서비스예요. 이 개요 문서는 Postmark API의 전반적인 구조, 인증 방식, HTTP 응답 코드, 그리고 API 에러 코드 체계를 정리한 내용이에요. REST 원칙을 따르는 Postmark API는 HTTPS를 통해 모든 요청에 TLS 암호화를 적용하고, 인증된 사용자라면 지정된 HTTP 요청 방식으로 API의 URI를 자유롭게 호출할 수 있어요.

출처: 문서

본문

이메일 전송 API 개요

Postmark API는 REST 원칙을 기반으로 만들어져 있어요. 인증된 사용자는 지정된 HTTP 요청 메서드를 사용해 Postmark의 어떤 URI와도 상호작용할 수 있으며, 모든 요청은 HTTPS를 통해 전송되어 TLS 암호화가 적용돼요. API의 기본 엔드포인트 URL은 아래와 같아요.

https://api.postmarkapp.com

이메일 전송뿐 아니라 벌크 전송, 바운스 관리, 템플릿, 서버·메시지 스트림·도메인 관리, 통계, 웹훅, 수신 이메일 처리 등 다양한 엔드포인트를 제공해요. 개별 엔드포인트마다 필요한 인증 헤더가 문서에 명시되어 있어요.

인증 (Authentication)

Postmark API의 모든 요청에는 올바른 API 토큰을 담은 HTTP 헤더를 보내 인증해야 해요. Postmark에는 두 가지 유형의 API 토큰이 있어요.

서버 토큰 (Server Token) — X-Postmark-Server-Token

서버 레벨 권한이 필요한 요청에 사용해요. Postmark 서버의 API Tokens 탭에서 찾을 수 있고, 계정 소유자, 계정 관리자, 그리고 해당 서버에 Server Admin 권한이 있는 사용자가 접근할 수 있어요.

계정 토큰 (Account Token) — X-Postmark-Account-Token

계정 레벨 권한이 필요한 요청에 사용해요. Postmark 계정의 API Tokens 탭에서 찾을 수 있고, 계정 소유자와 계정 관리자가 접근할 수 있어요.

각 API 엔드포인트의 레퍼런스 페이지에는 항상 어떤 인증 헤더를 사용해야 하는지 명시되어 있어요. 헤더 이름과 값은 대소문자를 구분하지 않아요. 요청에 잘못되거나 빠진 헤더가 있으면 HTTP 401 (Unauthorized) 응답을 받아요.

통합 테스트를 할 때 실제로 수신자에게 배달되지 않는 테스트 이메일을 보내고 싶다면, X-Postmark-Server-Token 헤더 필드에 POSTMARK_API_TEST 값을 넘겨서 데이터가 유효한지만 확인할 수 있어요.

HTTP 응답 코드

코드 의미 설명
200 Success 모든 작업이 정상적으로 처리됐어요.
401 Unauthorized 헤더에 API 토큰이 없거나 잘못됐어요.
404 Entity doesn't exist 요청한 리소스/엔티티가 존재하지 않아요. 엔드포인트와 ID가 올바른지 확인하세요.
413 Payload Too Large Email API의 10MB, Batch Email API의 총 50MB 크기 제한을 초과했어요.
415 Unsupported Media Type 요청에 필요한 헤더가 빠져 있어요.
422 Unprocessable Entity JSON 형식이 잘못되거나 필드가 유효하지 않아요. 응답 본문에 에러 코드와 상세 메시지가 담겨요.
429 Rate Limit Exceeded API 사용량 한도를 초과했어요. 요청 속도를 줄여야 해요.
500 Internal Server Error Postmark 서버 쪽 문제로, 대부분 메시지가 처리 중 유실되며 조사가 진행돼요.
503 Service Unavailable 계획된 서비스 점검 중에 반환되는 응답이에요.

API 에러 코드

Postmark API가 요청에서 문제를 감지하면 숫자형 ErrorCode와 사람이 읽을 수 있는 Message를 담은 JSON 본문을 반환하고, X-PM-ApiErrorCode 응답 헤더에 코드를 함께 실어 보내요. 대부분의 입력 오류는 HTTP 422를 사용하지만, 인증 실패(401)나 점검(503)처럼 다른 상태 코드를 쓰는 경우도 있어요. 하나의 ErrorCode가 여러 관련 메시지를 포함할 수 있어요.

{
  "ErrorCode": 403,
  "Message": "Invalid request field(s): 'From'."
}

ErrorCode 필드를 활용해 오류 유형을 프로그램적으로 감지할 수 있어요. 주요 에러 코드는 다음과 같아요.

  • 인증 (Authentication): 10 — 요청에 유효한 Server/Account 토큰이 없거나, 엔드포인트에 잘못된 토큰 유형을 사용한 경우 (HTTP 401)
  • 글로벌 (Global): 100 (503, 점검), 101 (500, 내부 오류)
  • 전송 (Sending): 배치 전송은 HTTP 200 응답 안에 메시지별 코드를 반환해요. 300 전송 검증, 402 잘못된 JSON, 403 잘못된 요청 필드, 410 단일 배치 요청 500건 제한, 411 허용되지 않은 첨부파일 타입, 413 발송 승인 대기 중, 422 잘못된 Server/Account 등
  • 템플릿 (Templates): 601 템플릿 push 서버 미발견, 1100~1131 — 잘못된 템플릿 유형, 충족되지 않은 레이아웃 규칙 등
  • 서버 (Servers): 600~606 — 서버 목록 페이징, 중복 도메인/이름, 삭제 권한, 잘못된 hook URL 등

사용 예시

테스트 이메일을 보내고 싶을 때는 서버 토큰 헤더에 POSTMARK_API_TEST 값을 넣어 데이터 유효성을 확인할 수 있어요.

X-Postmark-Server-Token: POSTMARK_API_TEST

실제 이메일 전송은 Email API 엔드포인트에 서버 토큰을 담아 요청하면 돼요. 자세한 요청/응답 형식은 각 엔드포인트 레퍼런스 문서에서 확인할 수 있어요.

더 알아보기 (Learn more)