ZZEM Mail · 개발자 문서

Mail API v1

도메인 등록·검증, Alias·전달 목적지 관리, 메일 로그 조회를 REST API 로 자동화하세요. 에이전시라면 고객 도메인 수십 개의 온보딩을 스크립트 하나로 끝낼 수 있습니다.

AUTHENTICATION

인증

콘솔 → API 키에서 키를 발급하세요. 시크릿은 발급 직후 한 번만 표시됩니다. 모든 요청에 Bearer 헤더로 전달합니다.

curl https://zzem.co.kr/api/v1/mail/domains \
  -H "Authorization: Bearer mk_xxxxxxxxxxxx.<secret>"

PLANS

플랜별 이용 범위

작업	Free	Basic 이상
조회(GET) — 도메인·Alias·목적지·로그	가능	가능
생성·삭제·검증(POST/DELETE)	불가(403 plan_required)	가능

Free 플랜도 콘솔에서는 같은 작업을 무료로 할 수 있습니다. 생성 계열 API 는 플랜의 도메인·Alias 한도를 콘솔과 동일하게 적용합니다.

ENDPOINTS

엔드포인트

메서드	경로	설명
GET	/api/v1/mail/domains	도메인 목록(검증·DNS 상태 포함)
POST	/api/v1/mail/domains	도메인 등록 — 응답에 설정할 DNS 레코드 포함
POST	/api/v1/mail/domains/{id}/verify	DNS 재검사·소유권 검증
DELETE	/api/v1/mail/domains/{id}	도메인 등록 해제
GET	/api/v1/mail/domains/{id}/aliases	Alias 목록(연결 목적지 포함)
POST	/api/v1/mail/domains/{id}/aliases	Alias 생성 + 목적지 연결
DELETE	/api/v1/mail/domains/{id}/aliases/{aliasID}	Alias 삭제
GET	/api/v1/mail/domains/{id}/destinations	전달 목적지 목록
POST	/api/v1/mail/domains/{id}/destinations	목적지 추가(클릭 인증 메일 발송)
GET	/api/v1/mail/domains/{id}/smtp	SMTP 발신 계정 목록
POST	/api/v1/mail/domains/{id}/smtp	발신 계정 발급 — 비밀번호는 응답에서 1회만 반환
DELETE	/api/v1/mail/domains/{id}/smtp/{credID}	발신 계정 폐기
GET	/api/v1/mail/domains/{id}/events	메일 로그(?limit=&offset=)
GET	/api/v1/mail/domains/{id}/dkim	DKIM 상태 — selector·TXT 값·DNS 반영 여부
POST	/api/v1/mail/domains/{id}/dkim	DKIM 발급 — 이미 있으면 그대로 반환(멱등)

EXAMPLES

고객 도메인 온보딩 예시

1) 도메인 등록

curl -X POST https://zzem.co.kr/api/v1/mail/domains \
  -H "Authorization: Bearer $ZZEM_MAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "client-a.co.kr"}'

# → {"id": 12, "domain": "client-a.co.kr", "status": "pending",
#    "dns": {"verification_txt": {...}, "mx": [...], "spf_txt": {...}}}

응답의 dns 값을 고객 DNS 에 등록한 뒤 다음 단계로 넘어갑니다.

2) 검증

curl -X POST https://zzem.co.kr/api/v1/mail/domains/12/verify \
  -H "Authorization: Bearer $ZZEM_MAIL_KEY"

# → {"verified": true, "mx_ok": true, "spf_ok": true, ...}

3) 목적지 추가 → Alias 연결

# 전달받을 이메일 등록(수신자에게 클릭 인증 메일이 갑니다)
curl -X POST https://zzem.co.kr/api/v1/mail/domains/12/destinations \
  -H "Authorization: Bearer $ZZEM_MAIL_KEY" -H "Content-Type: application/json" \
  -d '{"email": "owner@gmail.com"}'
# → {"id": 34, "status": "pending", "verification_mail_sent": true}

# 인증 완료 후: ceo@client-a.co.kr → owner@gmail.com
curl -X POST https://zzem.co.kr/api/v1/mail/domains/12/aliases \
  -H "Authorization: Bearer $ZZEM_MAIL_KEY" -H "Content-Type: application/json" \
  -d '{"local_part": "ceo", "destination_ids": [34]}'

4) SMTP 발신 계정 발급

curl -X POST https://zzem.co.kr/api/v1/mail/domains/12/smtp \
  -H "Authorization: Bearer $ZZEM_MAIL_KEY" -H "Content-Type: application/json" \
  -d '{"local_part": "outbound"}'

# → {"id": 5, "username": "outbound@client-a.co.kr",
#    "password": "…(이 응답에서만 표시)…", "daily_send_limit": 20000,
#    "smtp": {"host": "smtp.zzem.co.kr", "port": 587, "starttls": true}}

비밀번호는 해시로만 저장되므로 응답에서 바로 저장하세요. 클라이언트 설정 방법은 SMTP 설정 가이드 참고.

오류 형식

{"code": "plan_required", "message": "API 를 통한 생성·삭제는 유료 플랜(Basic 이상) 전용입니다. ..."}

# 주요 코드: unauthorized · plan_required · limit_reached ·
#           validation_error · already_exists · not_found

API 키 발급하기 SMTP 설정 가이드

4) DKIM 발급 → DNS 등록까지 자동화

발급은 멱등합니다 — 이미 키가 있으면 새로 만들지 않고 기존 값을 돌려줍니다. 받은 TXT 값을 Domain API 로 그대로 넣으면 콘솔에 들어갈 일이 없습니다.

DKIM=$(curl -s -X POST https://zzem.co.kr/api/v1/mail/domains/12/dkim \
  -H "Authorization: Bearer $ZZEM_MAIL_KEY" -H 'Content-Type: application/json' -d '{}')

echo "$DKIM"
# {"domain":"ie-news.co.kr","issued":true,"selector":"zzem",
#  "txt_host":"zzem._domainkey.ie-news.co.kr","txt_value":"v=DKIM1; k=rsa; p=MIIBIjAN...",
#  "dns_verified":false}

# 받은 값을 그대로 DNS 에 등록
curl -s -X POST https://zzem.co.kr/api/v1/domain/domains/ie-news.co.kr/records \
  -H "Authorization: Bearer $ZZEM_DOMAIN_KEY" -H 'Content-Type: application/json' \
  -d "{\"name\":\"zzem._domainkey\",\"type\":\"TXT\",
       \"content\":$(echo "$DKIM" | jq '.txt_value'),\"ttl\":\"3600\"}"

키 교체 주의: {"rotate":true} 로 요청하면 새 키로 바뀝니다. selector 가 zzem 으로 고정이라, DNS TXT 를 새 값으로 바꾸기 전까지 그 도메인의 발신 메일은 DKIM 검증에 실패합니다. 평소 운영에서는 rotate 없이 호출하세요.