Email Account

Email Account는 한 Space에 등록하는 SMTP 발신자입니다. 메일을 보낼 서버 주소와 로그인 정보, 그리고 발신 주소를 하나로 묶어 저장해 두는 리소스입니다. Script의 EmailSend statement가 실행될 때, 이 Email Account를 통해 실제 메일이 나갑니다. 예를 들어 옷가게 쇼핑몰에서 주문이 들어올 때마다 확인 메일을 보내려면, 먼저 발송에 쓸 Email Account를 등록해 두고 Script가 그것을 참조하게 합니다.

Email Account는 CMA에서 관리하는 Space 하위 리소스이며, 경로는 /spaces/{spaceId}/email-accounts를 기준으로 합니다. 발행(publish) 개념이 없습니다. 상태값이나 발행 단계 없이, 생성하면 곧바로 발송에 쓸 수 있습니다. 대신 생성은 무해한 조회성 동작이 아니라 실제로 메일을 한 통 보내 설정을 검증하는 동작이라는 점, 그리고 접속 정보(endpoint·username·password)는 한 번 만들면 바꿀 수 없다는 점을 아래에서 다룹니다.

리소스 구조

다음은 Email Account를 생성했을 때의 응답입니다. sys(시스템 속성)에 식별자와 버전이, 본문에 발신자 설정(name·endpoint·username·fromAddress·fromName)이 담깁니다. 비밀번호(password)는 응답 어디에도 나오지 않습니다.

{
  "sys": {
    "id": "3trmXRMdKpLc7GfNbyVQeR2WsT9LnU",
    "type": "EmailAccount",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-08-04T05:12:44.108Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-08-04T05:12:44.108Z",
    "version": 1
  },
  "name": "주문 알림 발송",
  "endpoint": {
    "host": "smtp.gmail.com",
    "port": 587,
    "security": "StartTls"
  },
  "username": "orders@example-shop.com",
  "fromAddress": "orders@example-shop.com",
  "fromName": "옷가게 주문"
}

주요 키:

• sys.id: Email Account의 고유 식별자입니다. 단일 조회·수정·삭제 경로의 {emailAccountId}에 들어갑니다.
• sys.version: 리소스 버전입니다. 1부터 시작하며 수정할 때마다 올라갑니다. 수정 요청에 이 값을 X-Weegloo-Version 헤더로 실어 보냅니다(아래 상태와 제약 참조).
• name: 콘솔에 보이는 라벨입니다(예: 주문 알림 발송). 발송에 쓰이지 않으며, From 표시명이 아닙니다. 여러 발신자를 구분하기 위한 이름일 뿐입니다.
• endpoint: 연결할 SMTP 서버입니다. host·port·security 세 값으로 이루어집니다.
• username: SMTP 로그인 사용자명입니다. 제공자마다 다릅니다. 메일 주소 그대로일 수도 있고, 발송 서비스가 정한 고정 문자열이거나 도메인 단위 로그인일 수도 있습니다.
• fromAddress: 발신 주소입니다. 보내는 봉투의 반송처(MAIL FROM)이자 받는 사람에게 보이는 From 주소로 함께 쓰입니다.
• fromName: From 헤더에 보이는 표시명입니다(선택). 없으면 주소만 나옵니다.

비밀번호(password)는 생성 요청 본문으로만 보내는 쓰기 전용 값이라, 위 응답에도, 이후 조회·목록 어디에도 되돌아오지 않습니다. username은 조회 응답에 입력한 값 그대로 나옵니다.

시스템 속성 (sys)

모든 Email Account는 공통 시스템 속성을 sys 객체에 담습니다. space, createdBy, updatedBy는 Refer 모양({ "sys": { "id", "type": "Refer", "targetType" } })으로 들어갑니다.

본문 속성:

생성 요청 본문 전용 입력:

발신자 정보와 접속 정보

Email Account의 값은 두 종류로 나뉩니다. 이 구분이 무엇을 수정할 수 있는지를 결정합니다.

• 접속 정보 — endpoint·username·password. 생성 후에는 바꿀 수 없습니다. 발송 서버를 옮기거나 로그인 정보를 회전할 때는 새 Email Account를 만들고 기존 것을 삭제합니다. 비밀번호는 위에서 설명했듯 다시 읽을 수 없으므로, 분실했다면 재설정이 아니라 재생성으로 처리합니다.
• 발신자 정보 — name·fromAddress·fromName. 생성 후에도 수정(PUT)으로 바꿀 수 있습니다. 라벨을 정리하거나 발신 주소·표시명을 바꿀 때 쓰며, 이때 접속 정보는 그대로 유지됩니다.

생성 시 실제 메일이 발송됩니다

Email Account 생성은 설정을 저장만 하는 동작이 아닙니다. 저장하기 전에 서버가 입력한 endpoint·username·password로 실제 접속해 테스트 메일을 한 통 보냅니다. 발송 대상은 fromAddress이며, username이 다른 주소라면 그 주소까지 포함될 수 있습니다.

• 발송에 성공해야 리소스가 저장됩니다.
• 서버가 접속·인증·발송 중 어느 단계에서든 거부하면 아무것도 생성되지 않고 실패하며, 응답에 서버가 돌려준 실패 사유가 함께 담깁니다.

그러므로 잘못된 값으로 생성을 반복하면 그때마다 실제 발송이 시도된다는 점에 유의해야 합니다.

상태와 제약

생성·수정 시 지키는 값 제약입니다.

동작과 권한에 대한 규칙:

• 접속 정보는 불변입니다. Update(PUT)로 바꿀 수 있는 것은 name·fromAddress·fromName뿐입니다. endpoint·username·password를 바꾸려면 새로 만들고 기존 것을 삭제합니다.
• 수정에는 버전이 필요합니다. Update 요청에 현재 sys.version 값을 X-Weegloo-Version 헤더로 보냅니다. 값이 최신이 아니면 버전 충돌로 거부됩니다. 이때는 리소스를 다시 조회해 최신 sys.version으로 재시도합니다.
• 비밀번호는 다시 읽을 수 없습니다. 조회·목록 어디에도 나오지 않으므로, 분실 시 재설정이 아니라 재생성으로 처리합니다.
• 플랜에 따라 쓸 수 있는 SMTP 서버가 다릅니다. 프리셋으로 제공되는 제공자 호스트(Gmail·Naver·Resend·Brevo)는 낮은 플랜에서도 등록할 수 있습니다. 프리셋에 없는 임의(자체 호스팅) 호스트는 결제 수단이 등록되어 있어야 사용할 수 있습니다. 플랜별 정책은 요금제를 참조하세요.

API

아래 모든 엔드포인트의 기준 URL은 https://cma.weegloo.com/v1이며, Authorization 헤더에 CMA를 인증하는 Bearer 토큰이 필요합니다. 수정(PUT)에는 X-Weegloo-Version 헤더가 추가로 필요합니다.

관련 문서

• Script: EmailSend statement로 이 Email Account를 통해 메일을 보냅니다.
• SpaceRole: 이 Space의 리소스 접근 권한을 정의하는 역할.
• 요금제: 프리셋 제공자 호스트와 임의(자체 호스팅) SMTP 호스트의 사용 정책.