이메일 API

조직이 인증한 도메인에서 이메일을 보냅니다. 발송 도메인은 콘솔에서 추가하고 인증합니다. 이 API는 해당 도메인으로 메시지를 보내고 각 메시지의 처리 결과를 알려줍니다.

호출 한 번에 수신자 한 명에게 보냅니다. to에는 주소 하나만 지정할 수 있고 cc와 bcc는 지원하지 않습니다. 여러 명에게 보내려면 수신자마다 이 엔드포인트를 한 번씩 호출하세요. 여러 주소를 한 메시지에 넣으면 주소 하나가 잘못됐을 때 전체 발송이 거부될 수 있기 때문입니다.

POST/organizations/:orgId/mails

하나의 메시지를 보냅니다. html, text 또는 둘 다를 제공하세요.

REST 입력은 from, SDK 입력은 sender를 사용합니다. 반환 레코드는 모두 from을 사용합니다.

요청 본문

{
  "from": "hello@yourdomain.com",
  "to": "customer@example.com",
  "subject": "Welcome aboard",
  "html": "<p>Thanks for signing up.</p>",
  "text": "Thanks for signing up.",
  "tag": "signup"              // Optional label of your own, returned as-is
}

응답 201

{
  "mail": {
    "id": "a1b2c3d4e5f6...",
    "from": "hello@yourdomain.com",
    "to": "cu******@example.com",
    "status": "sent",
    "tag": "signup",
    "deliveredAt": null,
    "openedAt": null,
    "error": null,
    "createdAt": "2026-08-06T...",
    "updatedAt": "2026-08-06T..."
  }
}

수신자 주소는 마스크 처리된 상태로 반환되고 그대로 저장됩니다. 따라서 로그가 유출되거나 키를 탈취당해도 고객 목록이 노출되지 않습니다. 전체 주소가 필요하면 직접 별도로 보관하세요.

from에 지정한 도메인은 인증된 도메인과 정확히 일치해야 합니다. 인증된 도메인의 서브도메인은 사용할 수 없습니다.

오류

400  Missing or malformed from, to, subject, or body, or a bad Idempotency-Key
403  That sending domain is not registered to this organization
409  Sending domain is not ready, or this Idempotency-Key was used with a different message
429  Send rate limit exceeded (5 messages/second). Wait retryAfter seconds
502  Send result is uncertain; use the returned mail id to check its status

429를 받으면 오류의 retryAfter에 표시된 초만큼 기다린 뒤 같은 Idempotency-Key와 같은 메시지로 다시 시도하세요. 제한은 조직별·초당 적용됩니다. 즉시 반복해서 재시도하지 마세요.

중복 발송 없이 재시도하기

다음 Idempotency-Key 헤더에 최대 256자의 고유한 문자열을 넣으면 같은 요청을 재시도할 때 두 번째 메시지를 보내는 대신 기존 메시지를 반환합니다. 응답을 보기 전에 요청이 끝났더라도 이미 발송되었을 수 있습니다. 키 없이 반복하면 두 번 과금되고 두 번 전달되므로 이 헤더가 타임아웃 상황의 재시도를 안전하게 만듭니다.

동작

Same key, same message   200 with the original message (201 was the first send)
Same key, different message   409. Use a new key for each distinct message
Lost response or 502   Check the mail id if known; otherwise replay only with the original key and content
No original key   Check mail history; do not blindly resend
New operation   Use a new key, for example for each new password reset
429   Wait retryAfter, then retry with the same key and message

GET/organizations/:orgId/mails

조직이 보낸 메시지를 최신 순으로 조회합니다. 한 번에 받을 개수는 limit(1~100, 기본값 50)으로 정하고, 다음 페이지는 cursor로 요청하세요.

응답

{
  "mails": [
    {
      "id": "a1b2c3d4e5f6...",
      "from": "hello@yourdomain.com",
      "to": "cu******@example.com",
      "status": "delivered",
      "tag": "signup",
      "deliveredAt": "2026-08-06T...",
      "openedAt": null,
      "error": null,
      "createdAt": "2026-08-06T...",
      "updatedAt": "2026-08-06T..."
    }
  ],
  "nextCursor": 41
}

다음 페이지를 가져올 때 nextCursor를 cursor로 보내세요. 마지막 페이지에서는 null입니다.

GET/organizations/:orgId/mails/:mailId

발송할 때 반환된 id로 하나의 메시지를 가져옵니다.

상태 값

sent         Accepted for delivery. Every message starts here.
delivered    The receiving server accepted it. deliveredAt is set.
bounced      Permanent delivery failure. Stop sending to this address.
complained   The recipient marked it as spam. Stop sending to this address.
rejected     A virus was found in the message and it was not delivered.
failed       Unconfirmed send or a final transient/undetermined bounce. Check error; do not blindly resend.

상태는 비동기로 갱신되며, 늦게 반영되거나 순서가 바뀔 수 있습니다. 잠시 뒤 다시 조회하세요. 배달 지연은 최종 실패가 아니며, 뒤늦게 반송이나 스팸 신고가 접수되면 delivered 상태도 바뀔 수 있습니다.

HTML 메일에는 열람 추적 이미지가 포함되며 메일별로 끄는 옵션은 없습니다. 이미지 차단과 미리 읽기 때문에 열람 수는 참고 정보입니다. Delivered는 수신 서버가 메일을 받았다는 뜻이며 받은편지함 도착을 보장하지 않습니다.

JustDeploy는 Amazon SES를 통해 메일을 보냅니다. 콘솔에 표시된 DKIM 레코드 3개는 메일 서명에 사용됩니다. 예전에 쓰던 메일 서비스와 공급자 이름이 같아도 삭제하지 마세요.

기본 봉투 발신자는 amazonses.com 도메인을 사용합니다. 화면에 보이는 From 도메인에 SPF를 추가해도 이 경로는 바뀌지 않습니다. From 도메인과 일치하는 유효한 DKIM으로 DMARC를 통과할 수 있지만 받은편지함 도착을 보장하지는 않습니다. 다른 발송 서비스에 필요한 DNS 레코드는 유지하세요.

GET/organizations/:orgId/mails/guide

이메일 발송 가이드인 MAIL.md를 반환합니다. 조직의 발송 도메인과 현재 상태가 채워져 있습니다.

응답

{ "guide": "# Sending email with JustDeploy\n..." }

반송과 스팸 신고는 조직별로 집계되며 둘 중 하나라도 너무 높아지면 조직 전체의 발송이 중지됩니다.