이메일 발송(SES)

워크스페이스에 AWS SES를 연결하면 자체 도메인으로 이메일을 발송할 수 있습니다. 대시보드 채널 › 이메일 › SES 연결의 온보딩 위저드가 권한 부여부터 DNS 검증까지 안내합니다. 연결 작업(권한·자격증명·도메인 설정)은 owner 또는 admin 역할이 필요하며, 상태 조회는 viewer도 가능합니다.

연결 방식은 두 가지입니다.

모드	대상	동작
새로 설정 (provision)	SES를 처음 쓰는 경우	Posmit이 도메인 identity 생성, DKIM, MAIL FROM, 전달 추적(SNS 콜백)까지 셋업합니다.
기존 SES 채택 (adopt)	이미 SES에서 검증된 도메인이 있는 경우	AWS 리소스를 거의 읽기 전용으로 사용합니다. identity·DKIM·MAIL FROM은 변경하지 않으며, 전달 추적만 선택적으로 켤 수 있습니다(`enableTracking`).

온보딩 위저드 단계

권한 부여

Posmit이 사용할 IAM 액세스 키를 준비합니다. 필요한 IAM 액션 목록은 모드에 따라 다르며 위저드가 자동으로 보여줍니다 (GET /v1/ses/permissions?mode=provision|adopt&tracking=true|false). provision은 identity 생성·구성세트·SNS 설정 권한까지, adopt는 조회·발송 위주의 최소 권한만 요구합니다.

키를 만드는 방법은 두 가지입니다.

CloudFormation(권장): 위저드의 “Launch Stack” 버튼(또는 템플릿 파일 다운로드 후 직접 업로드)으로 최소 권한 IAM 사용자와 액세스 키를 자동 생성합니다. 스택 이름은 posmit-ses-setup이며, 생성 완료 후 스택의 Outputs 탭에서 AccessKeyId / SecretAccessKey를 복사합니다.
IAM 정책 직접 적용: 위저드가 생성해 주는 IAM 정책 JSON을 기존 사용자에게 붙이고 액세스 키를 발급합니다.

Posmit은 AWS 콘솔에서의 작업을 자동화하지 않습니다. 딥링크와 산출물(템플릿·정책 JSON)만 제공하므로 실제 생성은 직접 확인하며 진행합니다.

키 검증

발급한 액세스 키를 입력하면 SES 계정 정보로 유효성을 확인합니다.


curl -X POST https://api.posmit.io/v1/ses/credentials/verify \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accessKeyId": "AKIAXXXXXXXX", "secretAccessKey": "YOUR_AWS_SECRET", "region": "ap-northeast-2" }'

응답에서 샌드박스 여부(sandbox), 발송 활성 상태, 발신 한도(sendQuota)를 확인할 수 있습니다. 기본 리전은 ap-northeast-2(서울)입니다.

도메인 선택

provision: 발신에 사용할 도메인(예: example.com)을 입력합니다.
adopt: 계정에 이미 등록된 도메인 identity 목록(POST /v1/ses/identities)에서 검증 완료된 도메인을 선택합니다. 아직 검증되지 않은 도메인은 채택할 수 없으며, 새로 설정 모드로 진행해야 합니다.

발신 설정

기본 발신자 주소(fromEmail)와 표시 이름(fromName)을 지정합니다. provision에서는 custom MAIL FROM 도메인(기본값 mail.example.com 형식, 프리픽스 mail 자동 완성)을 함께 설정합니다. adopt에서는 기존 구성세트 이름을 지정하거나 비워 둘 수 있습니다.

이 단계 완료 시 POST /v1/ses/domain/connect(또는 /v1/ses/domain/adopt)가 호출되어 identity·구성세트·SNS 전달 추적이 셋업되고, 등록해야 할 DNS 레코드 목록이 반환됩니다. 두 호출 모두 멱등이라 재시도해도 안전합니다.

DNS 등록

반환된 레코드를 도메인의 DNS에 등록합니다. 아래 “DNS 레코드” 절을 참고하세요. 지원되는 DNS 제공자라면 “한 번에 적용” 버튼(Domain Connect)으로 클릭 한 번에 등록할 수도 있습니다.

검증 확인

DNS 전파 후 위저드가 상태를 폴링합니다.

GET /v1/ses/status — 도메인 검증·DKIM·MAIL FROM 상태 (미연결 워크스페이스는 404)
GET /v1/ses/diagnose — 레코드별 적용 여부 진단
GET /v1/ses/stats — 샌드박스 여부와 발신 한도

모든 필수 레코드가 확인되면 연결이 완료되고, 이메일 채널에서 SES로 발송할 수 있습니다.

DNS 레코드

provision 기준으로 등록해야 하는 레코드는 다음과 같습니다. 실제 값은 위저드가 복사 가능한 형태로 제공합니다.

유형	이름	값	필수
CNAME ×3	`{token}._domainkey.example.com`	`{token}.dkim.amazonses.com`	필수 (DKIM 서명)
MX	`mail.example.com`	`feedback-smtp.ap-northeast-2.amazonses.com` (priority 10)	필수 (custom MAIL FROM 사용 시)
TXT	`mail.example.com`	`v=spf1 include:amazonses.com ~all`	필수 (SPF)
TXT	`_dmarc.example.com`	`v=DMARC1; p=none;`	권장 (DMARC)

진단: GET /v1/ses/diagnose는 공개 DNS 조회로 각 레코드를 ok / missing / mismatch / unknown으로 판정하고, “DKIM 2/3 적용 · SPF 누락 · DMARC 없음” 같은 요약을 제공합니다. DNS 제공자 API 토큰 없이 동작합니다.
Posmit이 DNS 레코드를 대신 등록하지는 않습니다. 산출·복사·진단까지만 제공합니다.

DNS 전파에는 수 분에서 수 시간이 걸릴 수 있습니다. 등록 직후 진단에서 missing으로 나와도 잘못 입력한 것이 아닐 수 있으니 잠시 후 다시 확인하세요.

Domain Connect 원클릭 적용

GET /v1/ses/dns/apply-url이 URL을 반환하면, 위저드에 “○○에 한 번에 적용” 버튼이 나타납니다. Domain Connect를 지원하는 DNS 제공자(GoDaddy, IONOS 등)에서 DKIM·MAIL FROM·DMARC 레코드를 한 번에 등록하는 서명된 딥링크입니다. 사용 중인 제공자가 지원하지 않거나 기능이 비활성 상태이면 버튼이 표시되지 않으며, 수동 등록 흐름을 그대로 사용하면 됩니다.

자격증명 처리

입력한 secretAccessKey는 브라우저 메모리에만 유지되고 연결 완료 즉시 지워집니다. 서버는 발송을 위해 암호화해 보관합니다.
이미 연결된 워크스페이스는 verify·connect·adopt 호출 시 키 입력을 생략할 수 있습니다. 액세스 키 두 필드를 모두 비우면 저장된 자격증명으로 폴백합니다(한 필드만 보내면 400).
SES 이벤트 콜백 URL의 인증 토큰은 2단계로 회전할 수 있습니다(owner/admin): POST /v1/ses/callback/secret/rotate(새 토큰 발급·재구독, 이전 토큰은 유예 기간 동안 유효) → POST /v1/ses/callback/secret/commit(이전 토큰 폐기). 이벤트 유실 없이 교체됩니다.

샌드박스 해제

새 SES 계정은 샌드박스 상태로 시작하며, 검증된 주소로만 발송할 수 있고 발신량도 제한됩니다.

테스트 수신자 검증: POST /v1/ses/identities/email로 특정 이메일 주소에 검증 메일을 보낼 수 있습니다(샌드박스 테스트용).
프로덕션 전환(샌드박스 해제)은 AWS 콘솔에서 신청해야 하며, 위저드의 검증 확인 단계에서 SES 계정 대시보드 링크로 안내합니다.

반송·불만 자동 차단 (Suppression)

연결 시 셋업되는 전달 추적은 SES 이벤트(발송·전달·반송·불만·거부·오픈·클릭)를 SNS를 통해 Posmit 콜백으로 수신합니다. 이 이벤트로 발송 결과가 전송 시도에 반영되고, 다음 규칙으로 suppression(수신 차단) 목록이 자동 관리됩니다.

이벤트	처리
영구 반송 (Permanent bounce)	발송 실패 처리 + 해당 주소를 `hard_bounce` 사유로 차단 목록에 등록
수신자 불만 (Complaint)	발송 실패 처리 + `complaint` 사유로 차단 목록에 등록
일시 반송 (Transient bounce)	발송 실패 처리만 — 차단하지 않습니다 (메일함 가득 참 등)

차단 목록의 효과는 두 곳에 적용됩니다.

발송 전 게이트: 차단된 주소로의 이메일 발송 요청은 공급자 호출 없이 실패 처리됩니다(“Recipient is on the email suppression list”).
뉴스레터 대상 제외: 캠페인 팬아웃 시 차단된 주소는 대상에서 자동 제외됩니다.

반송·불만 주소로 계속 발송하면 SES 평판이 하락해 계정 발송이 중단될 수 있습니다. 자동 차단은 발신 도메인 평판을 지키는 안전장치입니다.

오픈·클릭 트래킹

SES의 Open / Click 이벤트는 전달 상태와 분리해 참여 지표로 적재됩니다(클릭 이벤트는 링크 URL 포함).

오픈·클릭 지표는 참고용입니다. Apple Mail 개인정보 보호(MPP), 이미지 프록시, 보안 게이트웨이의 봇 프리페치 때문에 실제보다 부풀거나 누락될 수 있어 “읽음 확정”으로 해석하면 안 됩니다. 추세 분석·리스트 위생 점검 용도로 활용하세요.

다음 단계

뉴스레터

연결한 SES로 구독자에게 캠페인을 발송합니다.

템플릿

이메일 템플릿을 만들고 발송에 연결합니다.

채널 연결

이메일 외 다른 채널 공급자를 연결합니다.