mailinapp
Documentation menu

빠른 시작

발송 API를 사용하면 여러분의 백엔드가 이메일 발송을 직접 트리거할 수 있습니다 — Brevo, SendGrid, Postmark의 발송 엔드포인트를 호출하는 것과 같은 방식입니다. OTP, 영수증, 알림에 자연스럽게 어울리며, 스튜디오에서 디자인한 프로젝트를 여러분 자신의 데이터로 연락처 행을 대신해 트리거할 수도 있습니다.

키 발급하기

대시보드의 개발자에서 키 생성을 클릭하고 이름(예: "Production backend", "Staging")을 지정하세요. 전체 키 — mia_live_... — 는 딱 한 번만 표시됩니다. 안전한 곳에 저장해 두세요. MailInApp은 해시만 보관하므로 다시 조회할 방법이 없습니다. 키를 잃어버렸다면 취소하고 새로 발급하세요.

키는 특정 프로젝트가 아니라 계정 전체에 범위가 지정됩니다 — 하나의 키로 소유한 어떤 프로젝트든 트리거할 수 있습니다. 원하는 만큼(환경이나 연동마다 하나씩 두는 것이 흔한 패턴입니다) 만들 수 있으며, 각각을 독립적으로 언제든 취소할 수 있습니다.

발송 #1: 자유 형식

별도의 스튜디오 프로젝트 없이 순수한 트랜잭션 이메일을 보내려면, HTML과 텍스트를 직접 제공하세요.

curl -X POST https://mailinapp.com/api/v1/send \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Your one-time code",
    "html": "<p>Your code is 123456</p>",
    "text": "Your code is 123456"
  }'

성공적인 호출은 다음을 반환합니다.

{ "id": "abc123", "status": "sent" }

발송 #2: 템플릿

이것이 진짜 차별점입니다: 스튜디오에서 이메일을 시각적으로 디자인하고 — 폴백 엔진, 인터랙티브 블록, 병합 태그까지 — 여러분의 가입, 결제, 또는 지원 코드에서 mergeData로 데이터 소스 행을 대신해 트리거하세요.

curl -X POST https://mailinapp.com/api/v1/send \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345" \
  -d '{
    "to": "[email protected]",
    "projectId": "your-project-id",
    "mergeData": { "name": "Ada", "orderId": "12345" }
  }'

projectId는 프로젝트의 스튜디오 URL(/studio/<projectId>)에서 찾을 수 있습니다. mergeData 필드는 연락처 행과 정확히 동일한 방식으로 프로젝트의 {{field}} 병합 태그로 해석됩니다. 수신자는 다른 어떤 발송과도 같은 개인화된 서명 라이브 뷰 링크를 받으며 — 인터랙티브 블록(투표, 평점, 폼)이 작동하고, 모든 응답은 이 특정 API 호출에 귀속되어 해당 프로젝트의 일반 응답 뷰와 웹훅 전달로 흘러 들어갑니다.

Idempotency-Key 헤더는 선택 사항이지만, 재시도될 수 있는 작업(체크아웃 웹훅, 큐 컨슈머 등)으로 트리거되는 모든 호출에는 권장됩니다 — API 레퍼런스의 멱등성을 참고하세요.

발신자 재정의

두 발송 방식 모두 기본값으로 계정에 설정된 발신자 아이덴티티를 사용합니다 — 네이티브(SES) 발송을 사용 중이라면 설정 → 도메인의 "발신 주소" 카드, 그렇지 않다면 SMTP 릴레이의 발신 주소입니다. 한 번의 호출에 대해 이를 재정의하려면 from을 추가하세요. 예를 들어 특정 팀으로 발송하는 멀티 브랜드 계정의 경우입니다.

curl -X POST https://mailinapp.com/api/v1/send \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Your one-time code",
    "html": "<p>Your code is 123456</p>",
    "text": "Your code is 123456",
    "from": { "email": "[email protected]", "name": "Your Sales Team" }
  }'

from이 존재하는 한 from.email은 항상 필수입니다(이름만 재정의하는 것은 불가능합니다). from.name은 선택 사항입니다. 네이티브(SES) 발송에서는 from.email이 반드시 검증된 도메인 중 하나에 속한 주소여야 합니다 — 그 이유와 SMTP의 더 느슨한 규칙에 대해서는 API 레퍼런스의 발신 주소를 참고하세요.

대시보드에 이미 발신자 아이덴티티를 저장해 두었다면, 주소/이름을 인라인으로 반복하는 대신 그 id를 senderId로 전달하세요 — 두 필드 모두 API 레퍼런스를 참고하세요.

다음 단계

  • 전체 요청/응답 형태, type 의미, 속도 제한, 오류 코드: API 레퍼런스.
  • 여러분의 키로 이루어진 최근 호출들 — 상태와 오류를 포함해 — 은 감사(audit)를 위해 개발자 페이지에 표시됩니다.
  • 기존 SMTP 릴레이가 없나요? 네이티브 발송을 사용하면 도메인이 허용 목록에 등록되고 검증된 이후 MailInApp이 대신 발송해 줍니다.
  • API를 직접 호출하는 대신 AI 에이전트가 이메일을 만들거나 편집하게 하고 싶으신가요? 동일한 키가 MCP 서버도 인증하므로, Claude Desktop, Claude Code, 또는 다른 어떤 MCP 클라이언트든 채팅으로 대신 처리해 줄 수 있습니다.