Postmark API 메시지

Postmark Messages API는 특정 서버를 통해 보내거나 받은 모든 발신(outbound)·수신(inbound) 메시지의 상세 내용을 조회할 수 있는 API예요. 메시지가 보관되는 기간(보존 기간)은 기본 45일이며, 7일에서 365일 사이로 커스터마이즈할 수 있어요. 조회 기능뿐 아니라 메시지 발송 후 열람(open)·클릭(click)·반송(bounce) 같은 수신 상태를 추적하고, 차단된 수신 메시지를 우회하거나 처리 실패 메시지를 재시도할 수도 있어요.

출처: 문서

본문

개요

이 API는 이메일을 발송하는 대신 그 이후의 상태와 내용을 조회하는 용도로 써요. 즉 메시지를 보내는 것은 Email API(단일·배치 전송)나 Bulk API가 담당하고, Messages API가 그 메시지들의 검색·상세·원문 덤프·열람/클릭 추적 데이터를 제공하는 구조예요. 모든 요청은 서버 레벨 권한이 필요하며, 토큰은 Postmark 서버의 API Tokens 탭에서 확인할 수 있어요.

# 공통 요청 헤더
-H "Accept: application/json"
-H "X-Postmark-Server-Token: server token"

발신 메시지 검색

/messages/outbound 엔드포인트로 발신 메시지를 검색해요. 한 번의 검색으로 최대 10,000개까지 조회할 수 있고, 그 이상을 찾으려면 todate·fromdate 파라미터로 범위를 좁혀서 조회해요.

curl "https://api.postmarkapp.com/messages/[email protected]&count=50&offset=0&tag=welcome&status=sent&todate=2015-01-12&fromdate=2015-01-01" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"

주요 쿼리 파라미터:

count / offset — 요청당 반환할 메시지 수(최대 500)와 건너뛸 개수. count + offset은 10,000을 넘을 수 없어요.
recipient / fromemail — 수신자/발신자 이메일로 필터링
tag / subject — 태그·제목으로 필터링
status — 상태로 필터링(queued 또는 sent/processed). sent와 processed는 같은 결과를 반환해요.
todate / fromdate — 날짜 범위(포함). 예: 2021-01-01T12:00:00. API는 동부 시간대(Eastern Time)를 사용해요.
messagestream — 메시지 스트림 ID로 필터링. 지정하지 않으면 기본값은 outbound 트랜잭션 스트림이에요.
metadata_ — 메타데이터 값으로 필터링(예: metadata_color). 한 번에 하나의 메타데이터 필드만 검색할 수 있어요.

응답에서 TotalCount는 검색 조건에 맞는 메시지 수를 뜻해요. 여러 수신자에게 보낸 메시지는 Messages API에서 1건으로 세는 반면, Stats 페이지에서는 수신자마다 1건으로 세니까 주의하세요.

{
 "TotalCount": 194,
 "Messages": [
  {
   "Tag": "Invitation",
   "MessageID": "0ac29aee-e1cd-480d-b08d-4f48548ff48d",
   "MessageStream": "outbound",
   "To": [ { "Email": "[email protected]", "Name": null } ],
   "Cc": [],
   "Bcc": [],
   "Recipients": [ "[email protected]" ],
   "ReceivedAt": "2014-02-20T07:25:02.8782715-05:00",
   "From": "\"Joe\" <[email protected]>",
   "Subject": "staging",
   "Attachments": [],
   "Status": "Sent",
   "TrackOpens" : true,
   "TrackLinks" : "HtmlAndText",
   "Metadata": { "color": "blue", "client-id": "12345" },
   "Sandboxed": false
  }
 ]
}

발신 메시지 상세 조회

/messages/outbound/{messageid}/details로 특정 메시지의 본문·상태·이벤트 이력까지 조회해요.

curl "https://api.postmarkapp.com/messages/outbound/{messageid}/details" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"

응답에는 TextBody·HtmlBody·Body(원본), To·Cc·Bcc·Recipients, ReceivedAt, From, Subject, Attachments, Status(Sent·Processed·Queued), TrackOpens, TrackLinks, Metadata, Sandboxed가 포함돼요.

특히 MessageEvents 배열이 해당 메시지에 일어난 일들의 요약 목록을 제공해요. Type으로 Delivered(배달), Transient(일시적 실패), Opened(열람), LinkClicked(링크 클릭), Bounced(반송), SubscriptionChanged(구독 변경) 등을 구분할 수 있어요. 이를 통해서 특정 메시지의 수신 상태(Status)를 이벤트 단위로 파악할 수 있어요.

"MessageEvents": [
 { "Recipient": "[email protected]", "Type": "Delivered",
   "Details": { "DeliveryMessage": "smtp;250 2.0.0 OK l10si21599969igu.63 - gsmtp",
                "DestinationServer": "yahoo-smtp-in.l.yahoo.com (433.899.888.26)" } },
 { "Recipient": "[email protected]", "Type": "Opened",
   "Details": { "Summary": "Email opened with Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0" } },
 { "Recipient": "[email protected]", "Type": "Bounced",
   "Details": { "Summary": "smtp;550 5.1.1 ... does not exist", "BounceID": "374814878" } },
 { "Recipient": "[email protected]", "Type": "SubscriptionChanged",
   "Details": { "Origin": "Recipient", "SuppressSending": "True" } }
]

발신 메시지 원문 덤프

/messages/outbound/{messageid}/dump로 SMTP 원문 그대로의 소스를 얻을 수 있어요. 사용 가능한 덤프가 없으면 Body는 빈 문자열을 반환해요.

curl "https://api.postmarkapp.com/messages/outbound/{messageid}/dump" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"

수신 메시지 검색·상세

수신 메시지는 /messages/inbound 로 검색하고, /messages/inbound/{messageid}/details 로 상세를 조회해요. 발신과 달리 mailboxhash 필터가 있고, status 기본값은 processed라서 상태를 지정하지 않으면 처리된 메시지만 반환돼요. status 값으로 blocked·processed·queued·failed·scheduled를 쓸 수 있어요.

curl "https://api.postmarkapp.com/messages/[email protected]&count=50&offset=0&fromdate=2015-02-01&todate=2015-03-01&status=blocked" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"

수신 상세 응답에는 From·FromName·FromFull, To·ToFull·Cc·CcFull, ReplyTo, OriginalRecipient, Subject, Date, MailboxHash, TextBody·HtmlBody, Headers, Attachments, BlockedReason, Status가 포함돼요.

"BlockedReason": "Inbound request blocked by domain rule: [email protected]",
"Status": "Blocked"

차단된 수신 메시지 우회·실패 메시지 재시도

우회(bypass): 차단된 수신 메시지를 규칙을 통과시켜 처리하도록 해요.

curl "https://api.postmarkapp.com/messages/inbound/{messageid}/bypass" \
-X PUT \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"

재시도(retry): 처리에 실패한 수신 메시지를 다시 처리하도록 예약해요.

curl "https://api.postmarkapp.com/messages/inbound/{messageid}/retry" \
-X PUT \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token" \
-d ""

두 응답 모두 ErrorCode와 Message를 반환해요. 예: { "ErrorCode": 0, "Message": "Successfully bypassed message: 792a3e9d-...-fc78f87bf277." }

메시지 열람 추적(Opens)

/messages/outbound/opens로 열람 기록을 검색할 수 있어요. 여러 수신자에게 보낸 메시지를 두 명이 열면 각각 하나의 엔트리로 표현돼요.

curl "https://api.postmarkapp.com/messages/outbound/[email protected]&count=50&offset=0" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"

필터로 recipient, tag, messagestream, client_name, client_company, client_family, os_name, os_family, os_company, platform(webmail/desktop/mobile), country, region, city를 쓸 수 있어요. 응답의 각 Open에는 Client(어떤 메일 클라이언트로 열었는지), OS, Platform, Geo(IP 기반 국가·지역·도시·좌표), UserAgent, ReceivedAt가 들어가요. 다만 Postmark는 정보를 얻지 못한 필드는 응답에서 생략하므로, JSON을 읽을 때 누락을 허용해야 해요.

특정 메시지 하나의 열람 기록은 /messages/outbound/opens/{messageid} 로 조회해요. Postmark API는 첫 번째 열람만 저장하기 때문에 TotalCount는 항상 1이에요. 각각의 열람을 모두 받아야 한다면 Open 웹훅을 사용해야 해요.

curl "https://api.postmarkapp.com/messages/outbound/opens/{messageid}?count=10&offset=0" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"

메시지 클릭 추적(Clicks)

/messages/outbound/clicks로 링크 클릭 기록을 검색해요. 하나의 클릭은 하나의 수신자·고유 링크에 묶여요. 필터와 응답은 Opens와 유사하고, 응답에 ClickLocation(HTML/Text)과 OriginalLink(원본 링크)가 추가돼요.

curl "https://api.postmarkapp.com/messages/outbound/[email protected]&count=50&offset=0" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"

특정 메시지 하나의 클릭 기록은 /messages/outbound/clicks/{messageid} 로 조회해요.

웹훅과의 관계

Messages API는 요청-응답 방식의 풀(pull) 조회고, 웹훅(Webhooks)은 Postmark가 배달·반송·스팸 신고·열람·클릭·수신 이벤트를 사용자 서버로 실시간 push해 주는 방식이에요. 예를 들어 모든 열람을 빠짐없이 받아야 한다면 Open 웹훅을, 메시지 배달·반송 상태를 실시간으로 받으려면 Delivery/Bounce 웹훅을 설정하고, 과거 데이터를 백필(fill)하거나 필요할 때만 조회하려면 Messages API를 쓰면 돼요. 둘은 함께 쓰면 메시지의 전체 수신 상태를 완전하게 추적할 수 있어요.

더 알아보기 (Learn more)

공식 문서