ObjectOS이메일
트랜잭션 이메일 전송 제공자와 템플릿을 구성합니다.
이메일
ObjectOS는 애플리케이션에서 필요할 때(비밀번호 재설정, 초대, 승인 알림, 예약 보고서) 프레임워크의 이메일 플러그인을 통해 트랜잭션 이메일을 전송합니다. 플러그인에는 세 가지 전송 방식이 함께 제공됩니다.
전송 방식
| 제공자 | 사용 시점 | 필요한 env |
|---|---|---|
log | 로컬 개발용. 이메일을 전송하지 않고 stdout에 로깅합니다 | 없음 |
resend | Resend를 통한 SaaS 전달성 | OS_EMAIL_API_KEY |
postmark | Postmark를 통한 SaaS 전달성 | OS_EMAIL_API_KEY |
기본값은 log입니다. 실제 제공자가 구성되어 있지만 API 키가 제공되지
않은 경우 ObjectOS는 log 전송 방식으로 폴백합니다. 이는 비프로덕션
환경에서 실수로 메일이 전송되는 것을 방지하는 데 유용합니다.
SMTP는 어떤가요?
네이티브 SMTP 전송 방식은 현재 런타임에 내장되어 있지 않습니다. 환경에서 SMTP가 필요한 경우(기업 릴레이, 온프레미스 메일, 에어갭 배포) 두 가지 프로덕션급 옵션이 있습니다.
- SMTP-to-API 릴레이를 ObjectOS 앞단에서 실행합니다. Resend, Postmark, 그리고 자체 호스팅 대안(Postal, Cuttlefish)은 모두 SMTP 인그레스를 수용하고 자체 HTTP API를 통해 재전송합니다. ObjectOS는 평소처럼 HTTPS로 이들과 통신합니다.
- 사용자 정의 이메일 플러그인으로 런타임을 실행합니다. 이메일
플러그인 API는 작습니다(하나의
send(message)함수).nodemailer를 래핑하는 프로젝트 플러그인은requires목록을 통해 연결됩니다. spec 저장소의 플러그인 작성 가이드를 참고하세요.
네이티브 SMTP 전송 방식은 로드맵에 있습니다. 진행 상황은 github.com/objectstack-ai/objectos/issues에서 확인하세요.
환경 변수
| 변수 | 용도 |
|---|---|
OS_EMAIL_PROVIDER | log, resend, 또는 postmark |
OS_EMAIL_API_KEY | 제공자 API 키(Resend 또는 Postmark) |
OS_EMAIL_FROM | 기본 발신 주소. addr@x와 Name <addr@x> 형식을 모두 지원합니다 |
OS_EMAIL_RETRIES | 전송 실패 시 전송 재시도 횟수(기본값 0) |
환경 변수는 아티팩트의 email 구성 블록에서 일치하는 값을
재정의하므로, 운영자는 아티팩트를 다시 빌드하지 않고도 전송을 다시
지정할 수 있습니다.
템플릿
재사용 가능한 템플릿은 sys_email_template에 저장됩니다. 템플릿은
프레임워크의 템플릿 엔진이 평가하는 변수 보간을 지원합니다.
애플리케이션 코드(또는 플로우)는 템플릿 id와 변수 번들로 이메일
서비스를 호출합니다. 서비스는 제목/본문을 구체화하여 구성된 전송
방식에 전달합니다.
전달 확인
Resend / Postmark의 경우, 발신 도메인이 제공자 대시보드에 구성되어 있는지(SPF, DKIM, 선택적으로 DMARC) 확인하세요. 가장 빠른 엔드투엔드 점검 방법은 이메일 설정 페이지의 Console Send test email 작업입니다. 이는 실제 전송 방식을 사용하며 전송 오류를 인라인으로 표시합니다.
운영 지침
- API 키를 비밀로 취급하세요. 아티팩트가 아닌 고객의 시크릿 매니저에 저장하세요.
- 전송 오류 로그를 주시하세요. 제공자 속도 제한, 차단(suppression), 반송(bounce)이 모두 여기에 표시됩니다.
- 감사에 민감한 트랜잭션 메일(비밀번호 재설정, MFA 챌린지)은 고객의 정책에 따라 보존해야 합니다. 보존 기간은 전송 방식이 아닌 감사 로그에 설정하세요.
- 발신 메일은 비즈니스 트랜잭션을 차단하지 않습니다. 전송 실패는 오류로 표시되지만, 원본 레코드 변경을 롤백하지는 않습니다.