Postmark API 이메일 전송

Postmark API 이메일 전송

Postmark의 Email API는 하나의 서버(Server)를 통해 이메일을 발송하기 위한 전용 엔드포인트예요. POST /email로 단건을, POST /email/batch로 최대 500건까지 한 번에 발송할 수 있어요. 배치 요청은 첨부 파일을 포함해 페이로드 최대 50MB까지 허용해요.

출처: 문서

본문

단건 이메일 전송 — POST /email

이메일을 한 건 보낼 때는 https://api.postmarkapp.com/email에 POST 요청을 보내요. 필요한 요청 헤더는 다음과 같아요.

  • Content-Type (필수): application/json
  • Accept (필수): application/json
  • X-Postmark-Server-Token (필수): 서버 수준 권한이 필요한 토큰이에요. Postmark 서버의 API Tokens 탭에서 찾을 수 있어요.

curl 요청 예시는 다음과 같아요.

curl "https://api.postmarkapp.com/email" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Postmark-Server-Token: server token" \
-d '{
"From": "[email protected]",
"To": "[email protected]",
"Subject": "Password Reset",
"TextBody": "Click here to reset your password.",
"HtmlBody": "<html><body>Click here to <a href=\"#\">reset</a> your password.</body></html>",
"MessageStream": "outbound"
}'

요청 본문(Request Body) 필드

  • From (필수, string): 보내는 이메일 주소예요. 등록되고 확인된 Sender Signature(발신 서명)가 필요해요. 이름을 포함하려면 "Full Name <[email protected]>" 형식을 쓰면 되고, 최대 255자예요.
  • To (필수, string): 받는 이메일 주소로, 여러 개는 쉼표로 구분해요. To, Cc, Bcc를 합쳐 최대 50명까지예요.
  • Cc (string): 참조 주소로, 여러 개는 쉼표로 구분해요. 최대 50명(To, Cc, Bcc 합산)이에요.
  • Bcc (string): 숨은 참조 주소로, 여러 개는 쉼표로 구분해요. 최대 50명(To, Cc, Bcc 합산)이에요.
  • Subject (string): 제목 줄이에요. 최대 2000자예요.
  • Tag (string): 발신 이메일을 분류하고 상세 통계를 받는 데 쓰는 태그예요. 최대 1000자예요.
  • HtmlBody (string): TextBody가 없으면 필수예요. HTML 형식의 이메일 본문이에요.
  • TextBody (string): HtmlBody가 없으면 필수예요. 일반 텍스트 형식의 이메일 본문이에요.
  • ReplyTo (string): 회신 주소를 덮어쓰는 값이에요. 기본값은 발신 서명에 설정된 Reply To예요. 여러 주소는 쉼표로 구분해요.
  • Headers (array): 포함할 사용자 지정 헤더 목록이에요.
  • TrackOpens (boolean): 이 이메일에 대해 열람 추적(open tracking)을 활성화해요.
  • TrackLinks (string): HTML 또는 텍스트 본문의 링크에 대해 링크 추적을 활성화해요. 옵션은 None, HtmlAndText, HtmlOnly, TextOnly예요.
  • Metadata (object): 사용자 지정 메타데이터의 키/값 쌍이에요.
  • Attachments (array): 첨부 파일 목록이에요.
  • MessageStream (string): 전송에 사용할 메시지 스트림 ID예요. 지정하지 않으면 기본값으로 "outbound" 트랜잭션 스트림을 사용해요.

전체 필드를 포함한 요청 본문 예시는 다음과 같아요.

{
"From": "[email protected]",
"To": "[email protected]",
"Cc": "[email protected]",
"Bcc": "[email protected]",
"Subject": "Test",
"Tag": "Invitation",
"HtmlBody": "<b>Hello</b> <img src=\"cid:image.jpg\"/>",
"TextBody": "Hello",
"ReplyTo": "[email protected]",
"Headers": [
{
"Name": "CUSTOM-HEADER",
"Value": "value"
}
],
"TrackOpens": true,
"TrackLinks": "None",
"Attachments": [
{
"Name": "readme.txt",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "text/plain"
},
{
"Name": "report.pdf",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "application/octet-stream"
},
{
"Name": "image.jpg",
"ContentID": "cid:image.jpg",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "image/jpeg"
}
],
"Metadata": {
"color":"blue",
"client-id":"12345"
},
"MessageStream": "outbound"
}

응답(Response)

응답 필드는 다음과 같아요.

  • To (string): 받는 이메일 주소
  • SubmittedAt (string): 제출 시각
  • MessageID (string): 메시지 ID
  • ErrorCode (integer): API 오류 코드
  • Message (string): 응답 메시지

성공 시 응답 예시는 다음과 같아요.

HTTP/1.1 200 OK
Content-Type: application/json
{
"To": "[email protected]",
"SubmittedAt": "2014-02-17T07:25:01.4178645-05:00",
"MessageID": "0a129aee-e1cd-480d-b08d-4f48548ff48d",
"ErrorCode": 0,
"Message": "OK"
}

배치 이메일 전송 — POST /email/batch

여러 이메일을 한 번에 보내려면 https://api.postmarkapp.com/email/batch에 POST 요청을 보내면 돼요. 요청 헤더는 단건과 동일해요.

curl "https://api.postmarkapp.com/email/batch" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Postmark-Server-Token: server token" \
-d '[
{
"From": "[email protected]",
"To": "[email protected]",
"Subject": "Postmark test #1",
"TextBody": "Hello dear Postmark user.",
"HtmlBody": "<html><body><strong>Hello</strong> dear Postmark user.</body></html>",
"MessageStream": "outbound"
},
{
"From": "[email protected]",
"To": "[email protected]",
"Subject": "Postmark test #2",
"TextBody": "Hello dear Postmark user.",
"HtmlBody": "<html><body><strong>Hello</strong> dear Postmark user.</body></html>",
"MessageStream": "outbound"
}
]'

본문 필드는 단건 /email과 동일하며, 각 메시지마다 From, To, Subject, HtmlBody/TextBody, Tag, TrackOpens, TrackLinks, Attachments, Metadata, MessageStream 등을 지정할 수 있어요.

배치 응답 예시는 다음과 같아요.

HTTP/1.1 200 OK
Content-Type: application/json
[
{
"ErrorCode": 0,
"Message": "OK",
"MessageID": "b7bc2f4a-e38e-4336-af7d-e6c392c2f817",
"SubmittedAt": "2010-11-26T12:01:05.1794748-05:00",
"To": "[email protected]"
},
{
"ErrorCode": 406,
"Message": "You tried to send to a recipient that has been marked as inactive. Found inactive addresses: [email protected]. Inactive recipients are ones that have generated a hard bounce, a spam complaint, or a manual suppression. "
}
]

주의할 점은 /batch 엔드포인트는 개별 메시지의 검증이 실패하더라도 200 레벨의 HTTP 상태를 반환한다는 거예요. 응답의 각 메시지별 success와 error code를 꼭 확인해야 해요. (결과 순서는 원본 메시지 순서와 동일해요.)

더 알아보기 (Learn more)