Postly Cloud 개발자 문서
키 발급 →

Postly Cloud 개발자 문서

내 도메인 이메일을 발송·수신·문의폼·AI(MCP)로 내 서비스에 연동하는 방법을 안내합니다. 코딩 없이 쓰는 방법(MCP·위젯)부터 REST API까지 모두 다룹니다.

개요

Postly Cloud는 세 가지 연동 방식을 제공합니다. 목적에 맞게 고르세요.

방식대상용도
Postly MCP비개발자 (AI 사용자)AI 도구에 주소+키만 등록 → AI가 메일 발송·조회
임베드 위젯비개발자 (사이트 운영자)HTML 2줄로 문의폼 설치 → 받은편지함 수신
REST API개발자서버에서 직접 발송·목록·상세 호출, 수신 웹훅

빠른 시작

1) 대시보드 → 개발자에서 API 키를 발급합니다. 2) 발급 시 시크릿 키(sk_)는 한 번만 표시되니 안전하게 보관하세요. 3) 아래 방식 중 하나로 연동합니다.

발송 전제: 메일을 보내려면 보내는 주소의 도메인이 Postly에 발송 인증되어 있어야 합니다(대시보드 → 도메인 → 발송 연결).

인증

Base URL은 https://postlycloud.com 입니다. 키는 용도에 따라 두 종류입니다.

키접두어용도노출
시크릿 키sk_live_서버·AI 전용 (발송·조회·MCP)절대 공개 금지
퍼블리셔블 키pk_live_웹사이트 문의폼 (도메인 제한)브라우저 노출 가능

시크릿 키는 Authorization 헤더로 전달합니다.

http
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

API · 이메일 발송

POST/api/v1/emails

요청 본문

필드타입필수설명
fromstring✓보내는 주소 (인증된 내 도메인)
tostring✓받는 사람 이메일
subjectstring제목
textstring본문(텍스트)
htmlstring본문(HTML)
attachmentsarray{ filename, content(base64) } 최대 10개

예제

bash
curl https://postlycloud.com/api/v1/emails \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "안녕하세요",
    "text": "메일 본문입니다."
  }'
json
{ "id": "re_xxxxxxxx", "status": "sent" }

API · 메일 목록·상세

GET/api/v1/emails?folder=inbox&limit=50
쿼리기본값설명
folderinboxinbox · sent · spam · trash
limit50최대 100
bash
curl "https://postlycloud.com/api/v1/emails?folder=inbox" \
  -H "Authorization: Bearer sk_live_..."
json
{ "data": [
  { "id": "...", "from_addr": "[email protected]",
    "subject": "문의드립니다", "read": false, "created_at": "2026-06-26T..." }
] }

메일 1건 상세

GET/api/v1/emails/:id

본문(html·body_text)을 포함해 단건을 반환합니다.

API · 문의폼 (공개)

POST/api/v1/forms/submit

방문자가 보낸 문의를 사업자 받은편지함에 적재합니다. 브라우저에서 직접 호출하는 용도라 퍼블리셔블 키(pk_)를 사용하며, 키에 설정된 허용 도메인에서만 동작합니다.

필드필수설명
key✓퍼블리셔블 키 (pk_live_)
email✓방문자 이메일
message✓문의 내용
name방문자 이름
subject제목
javascript
fetch("https://postlycloud.com/api/v1/forms/submit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    key: "pk_live_...",
    email: "[email protected]",
    name: "홍길동",
    message: "제품 문의드립니다."
  })
})

Postly MCP (AI 연동)

코딩 없이, 사용하는 AI 도구(Claude 등)에 MCP 주소와 시크릿 키만 등록하면 AI가 내 도메인으로 메일을 보내고 받은 메일을 읽어줍니다.

항목값
MCP 주소https://postlycloud.com/api/mcp
전송 방식Streamable HTTP (JSON-RPC 2.0)
인증Authorization: Bearer sk_live_...

설치 방법 1) 원격 MCP — 설치 불필요(권장)

Postly MCP는 원격 HTTP 서버라 패키지 설치 없이 주소만으로 연결됩니다. Claude Code 예:

bash
claude mcp add --transport http postly https://postlycloud.com/api/mcp \
  --header "Authorization: Bearer sk_live_여기에_키"

설정 파일을 직접 쓰는 클라이언트라면:

json
{
  "mcpServers": {
    "postly": {
      "url": "https://postlycloud.com/api/mcp",
      "headers": { "Authorization": "Bearer sk_live_여기에_키" }
    }
  }
}

설치 방법 2) 오픈소스 커넥터(stdio)

stdio MCP만 지원하는 도구거나 npx 자동설치를 원하면 공개 커넥터 postlycloud-mcp를 사용하세요.

bash
claude mcp add postly -e POSTLY_API_KEY=sk_live_여기에_키 -- npx -y postlycloud-mcp
json
{
  "mcpServers": {
    "postly": {
      "command": "npx",
      "args": ["-y", "github:undefphoenixdev/postlycloud-mcp"],
      "env": { "POSTLY_API_KEY": "sk_live_여기에_키" }
    }
  }
}

제공 도구

도구설명주요 인자
send_email이메일 발송from, to, subject, text/html
list_emails메일 목록 조회folder, limit
get_email메일 1건 상세id
embed_mailbox메일함 임베드 iframe 코드 생성folder, accent, height

예: AI에게 “내 Postly 메일함을 내 홈페이지에 넣어줘” 라고 하면 AI가 embed_mailbox 도구로 iframe 코드를 만들어 줍니다. “어제 받은 문의 요약해서 [email protected] 로 보내줘” 면 list_emails+send_email을 씁니다.

메일함 임베드

Postly 메일함을 내 홈페이지나 사내 관리자 페이지에 iframe 으로 임베드할 수 있습니다. 가장 쉬운 방법은 위 Postly MCP에 연결한 AI에게 “메일함을 내 사이트에 넣어줘”라고 요청하는 것입니다. 직접 만들려면 아래 단계를 따르세요.

1) 임베드 토큰 발급 (서버에서)

토큰은 메일함 접근 권한이 담긴 단기 자격증명이라 반드시 서버에서 시크릿 키로 발급합니다(브라우저에 sk_ 노출 금지). 만료되면 다시 발급하세요.

POST/api/v1/embed/token
bash
curl https://postlycloud.com/api/v1/embed/token \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"folder":"inbox","ttl":3600}'
json
{
  "token": "....",
  "expires_in": 3600,
  "url": "https://postlycloud.com/embed/mailbox?token=...",
  "iframe": "<iframe src=\"...\" .../>"
}

2) iframe 삽입 (내 페이지에)

응답의 url(또는 iframe)을 내 페이지에 넣습니다. 토큰 만료 전에 서버에서 새 토큰을 받아 src를 갱신하세요.

html
<iframe
  src="https://postlycloud.com/embed/mailbox?token=발급받은_토큰&folder=inbox&accent=%237C3AED"
  style="width:100%;height:600px;border:0;border-radius:12px"
  title="내 메일함"></iframe>
파라미터설명
token서버에서 발급한 임베드 토큰 (필수)
folderinbox · sent · spam (기본 inbox)
accent강조 색상 hex (URL 인코딩, 예: %237C3AED)

현재 임베드 메일함은 읽기 전용(목록·본문 보기)입니다. 발송이 필요하면 REST API의 발송 엔드포인트를 함께 사용하세요.

임베드 위젯

내 사이트(워드프레스·카페24 등) HTML에 아래 두 줄을 넣으면 문의폼이 표시되고, 제출된 문의는 받은편지함으로 들어옵니다.

html
<div data-postly-form
     data-key="pk_live_여기에_퍼블리셔블_키"
     data-title="문의하기"
     data-accent="#7C3AED"></div>
<script src="https://postlycloud.com/embed.js" async></script>
data 속성설명
data-key퍼블리셔블 키 (필수)
data-title폼 제목 (기본: 문의하기)
data-accent버튼 색상 (기본: 브랜드 퍼플)

보안: 키 설정에서 허용 도메인을 지정하면 해당 사이트에서만 폼이 동작합니다.

수신 웹훅

메일이 도착하면 설정한 URL로 알림(POST)이 전송됩니다. 대시보드 키 설정에서 웹훅 URL을 등록하세요.

페이로드

json
{
  "event": "email.received",
  "id": "...",
  "folder": "inbox",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "문의드립니다",
  "text": "...",
  "received_at": "2026-06-26T..."
}

서명 검증

요청 헤더 X-Postly-Signature는 본문을 키의 webhook_secret으로 HMAC-SHA256 서명한 값입니다. 위조 방지를 위해 검증하세요.

javascript
import { createHmac } from "crypto"

function verify(rawBody, signature, webhookSecret) {
  const expected = createHmac("sha256", webhookSecret)
    .update(rawBody).digest("hex")
  return expected === signature
}

에러·상태 코드

코드의미
200 / 201성공
400잘못된 요청(필수 필드 누락 등)
401유효하지 않은 API 키
403발송 권한이 없는 도메인(미인증)
404리소스 없음
502발송 실패(도메인 발송 미인증 등)

MCP는 JSON-RPC 규약을 따릅니다. 인증 실패 시 error.code = -32001 을 반환합니다.

제한·보안

  • 시크릿 키(sk_)는 절대 브라우저·공개 저장소에 노출하지 마세요. 노출 시 즉시 대시보드에서 폐기하고 재발급하세요.
  • 문의폼·위젯에는 반드시 퍼블리셔블 키(pk_)와 허용 도메인을 사용하세요.
  • 발송은 본인 소유의 발송 인증된 도메인에서만 가능합니다(스푸핑 차단).
  • 첨부는 요청당 최대 10개입니다.
  • 발송량이 많아지면 발신 평판 보호를 위해 전용 IP 전환을 권장합니다(별도 안내).

바로 시작하기

대시보드에서 API 키를 발급하고 위 예제를 그대로 붙여 넣으세요.

API 키 발급하러 가기 →