Postmark API 템플릿
Postmark API 템플릿
Templates API는 특정 서버(Server)의 템플릿을 관리할 수 있게 해주는 API예요. 미리 만들어 둔 이메일 템플릿을 코드와 분리해 두고, 변수(Model)만 채워서 손쉽게 트랜잭셔널 이메일을 보낼 수 있어요. 참고로 서버 하나는 최대 100개의 템플릿을 가질 수 있고, 이 한도를 넘는 요청은 처리되지 않아요. 더 많은 템플릿이 필요하면 지원팀에 문의해야 해요.
이 문서에서는 템플릿의 생성·조회·수정·삭제 방법과, 템플릿 변수(TemplateModel) 그리고 템플릿을 이용해 이메일을 보내는 방법을 다뤄요. 모든 요청은 서버 수준 권한이 필요한 토큰(X-Postmark-Server-Token)을 사용하며, 이 토큰은 Postmark 서버의 API Tokens 탭에서 확인할 수 있어요.
출처: 문서
본문
템플릿으로 이메일 보내기 (Send email with template)
POST /email/withTemplate/ 엔드포인트로 템플릿을 사용해 이메일 한 통을 보내요. 템플릿은 TemplateId나 TemplateAlias로 지정하고, 화면에 채워 넣을 값은 TemplateModel로 전달해요. 템플릿에 CSS 스타일을 인라인으로 적용할지 여부는 InlineCss로 조절할 수 있어요(기본값 true).
curl "https://api.postmarkapp.com/email/withTemplate" \
-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]",
"TemplateId": 1234,
"TemplateModel": {
"user_name": "John Smith"
}
}'
TemplateId가 없으면 TemplateAlias로 대신 지정할 수 있어요. From은 등록·확인된 Sender Signature가 필요하고, 이름을 포함하려면 "Full Name <[email protected]>" 형식을 사용해요. To는 콤마로 구분해 최대 50개까지 지정할 수 있어요. TemplateModel은 중첩 객체도 지원해서 {{company.name}} 같은 변수도 사용할 수 있어요.
{
"TemplateId": 1234,
"TemplateModel": {
"user_name": "John Smith",
"company": {
"name": "ACME"
}
},
"InlineCss": true,
"From": "[email protected]",
"To": "[email protected]",
"Cc": "[email protected]",
"Bcc": "[email protected]",
"Tag": "Invitation",
"ReplyTo": "[email protected]",
"Headers": [
{
"Name": "CUSTOM-HEADER",
"Value": "value"
}
],
"TrackOpens": true,
"TrackLinks": "None",
"Attachments": [
{
"Name": "readme.txt",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "text/plain"
}
],
"Metadata": {
"color":"blue",
"client-id":"12345"
},
"MessageStream": "outbound"
}
템플릿으로 여러 이메일 한 번에 보내기 (Send batch with templates)
POST /email/batchWithTemplates 엔드포인트는 여러 수신자에게 서로 다른 변수를 넣어 템플릿 메일을 한 번의 호출로 보내요(Messages 배열). 호출당 최대 500개의 메시지를 받아줘요. 각 메시지는 TemplateId 또는 TemplateAlias로 템플릿을 지정할 수 있고, 둘 다 주면 TemplateId가 우선해요.
curl "https://api.postmarkapp.com/email/batchWithTemplates" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Postmark-Server-Token: server token" \
-d '{
"Messages": [
{
"From": "[email protected]",
"To": "[email protected]",
"TemplateId": 12345,
"TemplateModel": {
"fizz": "buzz"
}
},
{
"From": "[email protected]",
"To": "[email protected]",
"TemplateAlias": "welcome-notification",
"TemplateModel": {
"fizz": "buzz"
}
}
]
}'
주의할 점이 있어요. /batchWithTemplates는 개별 메시지의 검증이 실패하더라도 HTTP 200을 반환해요. 그래서 응답에 담긴 각 메시지의 ErrorCode와 Message를 반드시 확인해야 해요(응답 순서는 요청한 메시지 순서와 동일해요).
템플릿 변수 (Template variables)
템플릿 안에서는 Mustache 스타일의 {{ 변수명 }} 문법으로 값을 채워 넣어요. 변수는 TemplateModel로 전달하고, 중첩 객체({{company.name}})나 반복({{#each person}}), 조건({{#company}}) 블록도 지원해요. 템플릿을 만들 때 HtmlBody, TextBody, Subject에 이런 문법을 써서 재사용 가능한 레이아웃을 만들 수 있어요.
예를 들어 TypeScript SDK로 템플릿 알리아스(TemplateAlias)와 타입이 지정된 TemplateModel을 쓰면, 이메일 레이아웃을 애플리케이션 코드와 분리하고 보내기를 테스트하기 쉬워져요. 반환되는 MessageID로 배달·바운스 웹훅을 특정 트랜잭션에 연결할 수도 있어요.
import { ServerClient } from "postmark";
const client = new ServerClient(process.env.POSTMARK_SERVER_TOKEN!);
type ReceiptEmail = {
to: string;
receiptId: string;
amount: string;
dashboardUrl: string;
};
export async function sendReceiptEmail(input: ReceiptEmail) {
const message = await client.sendEmailWithTemplate({
From: "[email protected]",
To: input.to,
TemplateAlias: "receipt",
TemplateModel: {
receipt_id: input.receiptId,
amount: input.amount,
dashboard_url: input.dashboardUrl,
},
MessageStream: "outbound",
});
return message.MessageID;
}
템플릿 조회 (Get a template)
GET /templates/{templateIdOrAlias} 로 특정 템플릿의 내용을 가져와요. 경로에는 TemplateId나 Alias를 넣을 수 있어요.
curl "https://api.postmarkapp.com/templates/{templateIdOrAlias}" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"
응답에는 템플릿 이름·Subject·HtmlBody·TextBody뿐 아니라 Active(전송 가능 여부), Alias, TemplateType(Standard 또는 Layout), 그리고 레이아웃 템플릿을 쓴다면 그 Alias(LayoutTemplate)가 담겨요.
{
"Name": "Onboarding Email",
"TemplateId": 1234,
"Subject": "Hi there, {{Name}}",
"HtmlBody": "Hello dear Postmark user. {{Name}}",
"TextBody": "{{Name}} is a {{Occupation}}",
"AssociatedServerId": 1,
"Active": false,
"Alias": "onboarding-v1",
"TemplateType": "Standard",
"LayoutTemplate": "my-layout"
}
템플릿 생성 (Create a template)
POST /templates 로 새 템플릿을 만들어요. Name은 필수이고, HtmlBody나 TextBody 중 하나는 필수예요. Subject는 Standard 템플릿에만 필수이며, Layout 템플릿에는 Subject를 넣으면 API 오류가 나요. Alias는 숫자·ASCII 문자·., -, _만 허용되고 반드시 문자로 시작해야 해요.
curl "https://api.postmarkapp.com/templates" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Postmark-Server-Token: server token" \
-d '{
"Name": "Welcome Email",
"Alias": "onboarding-v1",
"HtmlBody": "<html><body>Hello{{name}}<body><html>",
"TextBody": "Hello, {{name}}",
"Subject": "Hello, from {{company.name}}",
"TemplateType": "Standard",
"LayoutTemplate": "my-layout"
}'
TemplateType은 Standard 또는 Layout 중 선택하며 기본값은 Standard예요. Layout 템플릿은 HtmlBody에 콘텐츠 자리 표시자를 정확히 한 번만 넣어야 해요. LayoutTemplate 필드로 Standard 템플릿이 사용할 기존 Layout 템플릿(Alias)을 지정할 수 있고, 레이아웃을 쓰지 않으려면 빈 문자열 ""로 null 처리해요. 생성 후에는 템플릿 타입을 바꿀 수 없어요.
템플릿 수정 (Edit a template)
PUT /templates/{templateIdOrAlias} 로 기존 템플릿을 수정해요. 수정 시 Name과 Subject는 필수고, HtmlBody 또는 TextBody 중 하나는 필수예요.
curl "https://api.postmarkapp.com/templates/{templateIdOrAlias}" \
-X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Postmark-Server-Token: server token" \
-d '{
"Name": "Onboarding Email",
"Subject": "Hello from {{company.name}}!",
"TextBody": "Hello, {{name}}!",
"HtmlBody": "<html><body>Hello, {{name}}!</body></html>",
"Alias": "welcome-v1"
}'
템플릿 목록 조회 (List templates)
GET /templates 로 서버의 템플릿 목록을 페이징해서 가져와요. Count와 Offset으로 페이지를 나누고, TemplateType(All/Standard/Layout)이나 LayoutTemplate(레이아웃 Alias)으로 필터링할 수 있어요.
curl "https://api.postmarkapp.com/templates?count=100&offset=0&LayoutTemplate=my-layout" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"
{
"TotalCount": 2,
"Templates": [
{
"Active": true,
"TemplateId": 1234,
"Name": "Password Recovery Email",
"Alias": "password-recovery",
"TemplateType": "Standard",
"LayoutTemplate": "my-layout"
},
{
"Active": true,
"TemplateId": 5678,
"Name": "Default Layout",
"Alias": "my-layout",
"TemplateType": "Layout",
"LayoutTemplate": null
}]
}
템플릿 삭제 (Delete a template)
DELETE /templates/{templateIdOrAlias} 로 템플릿을 삭제해요. 성공하면 ErrorCode: 0과 함께 삭제 메시지가 반환돼요.
curl "https://api.postmarkapp.com/templates/{templateIdOrAlias}" \
-X DELETE \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"
{
"ErrorCode": 0,
"Message": "Template 1234 removed."
}
기타 기능
다른 서버로 템플릿 푸시 — PUT /templates/push 로 한 서버의 템플릿을 다른 서버로 복사할 수 있어요. SourceServerID·DestinationServerID·PerformChanges를 받고, PerformChanges: false로 두면 실제 반영 없이 어떤 템플릿이 생성·수정될지 미리 확인(dry-run)할 수 있어요. 이 요청은 계정 수준 권한 토큰(X-Postmark-Account-Token)이 필요해요.
템플릿 검증 — POST /templates/validate 로 템플릿 문법이 올바른지, 어떤 변수 키가 필요한지 미리 확인할 수 있어요. TestRenderModel을 주면 렌더링 결과(RenderedContent)도 함께 보여주고, 응답의 SuggestedTemplateModel에 템플릿에서 발견된 모든 키 구조가 나와요. 검증은 HTML 표준을 검사하는 게 아니라 템플릿 문법이 파싱·렌더링 가능한지만 확인한다는 점 참고하세요.