도메인 추가 및 확인

hello@acme.com으로 보내려면 DNS 레코드를 게시해 acme.com을 소유하고 있음을 증명해야 합니다. 확인이 끝나면 DKIM 서명(수신 측이 메일이 실제로 내 도메인에서 왔음을 알 수 있게 합니다)과 사용자 지정 return path(SPF와 DMARC가 내 도메인과 정렬되게 합니다)가 설정됩니다.

도메인을 추가하기 전에

신규 팀은 먼저 짧은 발송 프로필을 작성해야 하며, 일부 도메인(무료 메일 제공업체, 최근 7일 안에 등록된 도메인)은 거부됩니다. 계정 인증 및 발송 한도를 참고하세요.

1. 도메인 추가

   Node.js

   add-domain.ts

   import { SpacePost } from "@spacepost/node";
   
   const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
   
   const { data: domain, error } = await spacepost.domains.create({ name: "acme.com" });
   if (error) throw new Error(`${error.name}: ${error.message}`);
   
   console.log(domain.id, domain.status); // "not_started" or "pending"
   for (const r of domain.records ?? []) {
     console.log(`${r.type.padEnd(5)} ${r.name} -> ${r.value}${r.priority ? ` (priority ${r.priority})` : ""}`);
   }

   cURL

   curl -X POST https://api.spacepost.dev/domains \
     -H "Authorization: Bearer $SPACEPOST_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "name": "acme.com" }'

   Python

   r = requests.post(
       "https://api.spacepost.dev/domains",
       headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
       json={"name": "acme.com"},
   )
   for rec in r.json()["records"]:
       print(rec["type"], rec["name"], rec["value"])

   대시보드나 spacepost domains add acme.com을 사용할 수도 있습니다.

2. DNS 레코드 만들기

   응답에는 records 배열과 recommended_records 배열(DMARC)이 들어 있습니다.

   Response (abridged)

   {
     "object": "domain",
     "id": "0192e1c4-0000-7000-8000-000000000001",
     "name": "acme.com",
     "status": "not_started",
     "region": "eu-central-1",
     "open_tracking": false,
     "click_tracking": false,
     "records": [
       { "record": "DKIM", "name": "a1b2c3d4e5f6._domainkey", "type": "CNAME", "ttl": "Auto", "status": "not_started", "value": "a1b2c3d4e5f6.dkim.amazonses.com" },
       { "record": "DKIM", "name": "g7h8i9j0k1l2._domainkey", "type": "CNAME", "ttl": "Auto", "status": "not_started", "value": "g7h8i9j0k1l2.dkim.amazonses.com" },
       { "record": "DKIM", "name": "m3n4o5p6q7r8._domainkey", "type": "CNAME", "ttl": "Auto", "status": "not_started", "value": "m3n4o5p6q7r8.dkim.amazonses.com" },
       { "record": "SPF", "name": "send", "type": "MX", "ttl": "Auto", "status": "not_started", "value": "feedback-smtp.eu-central-1.amazonses.com", "priority": 10 },
       { "record": "SPF", "name": "send", "type": "TXT", "ttl": "Auto", "status": "not_started", "value": "\"v=spf1 include:amazonses.com ~all\"" }
     ],
     "recommended_records": [
       { "record": "DMARC", "name": "_dmarc", "type": "TXT", "ttl": "Auto", "status": "not_started", "value": "\"v=DMARC1; p=none;\"" }
     ]
   }

   DNS 제공업체에서 추가하세요. 아래의 레코드 설명과 제공업체별 가이드를 참고하세요.

3. 확인

   DNS 변경이 반영되는 데 몇 분(드물게는 몇 시간)이 걸릴 수 있습니다. SpacePost는 대기 중인 도메인을 자동으로 다시 확인하며, 언제든 직접 확인을 요청할 수도 있습니다.

   Node.js

   verify-domain.ts

   import { SpacePost } from "@spacepost/node";
   
   const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
   const id = "0192e1c4-0000-7000-8000-000000000001";
   
   const { error } = await spacepost.domains.verify(id); // asks SpacePost to re-check DNS now
   if (error) throw new Error(error.message);
   
   const { data: domain } = await spacepost.domains.get(id);
   console.log(domain?.status); // "verified" once DKIM is confirmed

   cURL

   curl -X POST https://api.spacepost.dev/domains/$DOMAIN_ID/verify -H "Authorization: Bearer $SPACEPOST_API_KEY"
   curl https://api.spacepost.dev/domains/$DOMAIN_ID -H "Authorization: Bearer $SPACEPOST_API_KEY"

   CLI

   spacepost domains verify acme.com
   spacepost domains doctor acme.com   # looks up each record live and tells you what is missing or wrong

레코드 설명

API의 레코드 이름은 도메인에 대한 상대 이름입니다(send, _dmarc, a1b2c3d4e5f6._domainkey). 일부 DNS 제공업체는 전체 이름(send.acme.com)을 요구합니다. 어느 쪽인지는 제공업체별 가이드에 나와 있습니다.

레코드	유형	이름	값	용도
DKIM (3개)	CNAME	<token>._domainkey	<token>.dkim.amazonses.com	Amazon SES가 대신 교체해 주는 공개 키를 게시합니다(“Easy DKIM”). 수신 측은 이 키로 각 메시지가 내 도메인에서 서명되었고 변조되지 않았음을 확인합니다. 필수: 확인은 세 개 모두에 달려 있습니다.
Return path	MX	send	feedback-smtp.<region>.amazonses.com, 우선순위 10	send.acme.com으로 오는 반송 및 스팸 신고 알림을 수신합니다. 아래 TXT와 함께 사용자 지정 MAIL FROM 도메인을 이룹니다.
Return path	TXT	send	v=spf1 include:amazonses.com ~all	return path 서브도메인용 SPF입니다. 봉투 발신자가 내 도메인에 있으므로 SPF가 From 주소와 정렬되며, DMARC에 이것이 필요합니다.
DMARC (권장)	TXT	_dmarc	v=DMARC1; p=none;	인증에 실패한 메일을 수신 측이 어떻게 처리할지 알려 주며, Gmail과 Yahoo가 대량 발송자에게 요구합니다. DMARC를 참고하세요.

TXT 따옴표

API는 TXT 값을 따옴표로 감싸서 보여 줍니다("v=spf1 ..."). 대부분의 DNS 대시보드는 따옴표를 알아서 추가하므로 값은 따옴표 없이 입력하세요.

참고

도메인을 추가할 때 custom_return_path로 send 서브도메인 이름을 바꿀 수 있습니다. 사용자 지정 Return-Path를 참고하세요.

고객을 대신해 발송하는 플랫폼을 만들고 있나요? tenant_id(테넌트 ID 또는 사용자의 external_id)를 전달하면 도메인이 테넌트 소유가 되며, 이 도메인에서 나가는 메일은 자동으로 해당 테넌트에 귀속됩니다. 플랫폼 모드를 참고하세요.

상태

상태	의미
not_started	도메인이 추가되었으며 DNS가 아직 확인되지 않았습니다.
pending	SpacePost가 DNS를 확인하는 중입니다.
verified	DKIM이 확인되었습니다. 이 도메인에서 발송할 수 있습니다.
temporary_failure	조회가 일시적으로 실패했습니다. 자동으로 다시 시도합니다.
failed	72시간 안에 DNS를 찾지 못했거나 레코드가 잘못되었습니다. 레코드를 고친 뒤 verify를 다시 호출하세요.

DKIM이 통과하는 즉시 도메인은 verified가 됩니다. return path 레코드만 없는 경우에도 메일은 발송되지만 SPF 정렬이 Amazon의 도메인으로 대체되어 DMARC 정렬이 약해집니다. 최상의 전달률을 위해 바로잡으세요.

records의 각 레코드에도 같은 값을 쓰는 자체 status가 있으므로 어떤 레코드가 없는지 정확히 알 수 있습니다.

서브도메인에서 발송하기

acme.com이 확인되었다면 모든 서브도메인(news@mail.acme.com)에서 발송할 수 있습니다. 마케팅 메일은 트랜잭션 도메인과 평판을 분리할 수 있도록 서브도메인(mail.acme.com) 자체를 확인하는 것이 더 좋은 방식입니다.

한도

플랜	도메인
Free	3
Pro	10
Scale	1,000

다른 팀이 이미 등록한 도메인을 추가하면 422 validation_error(“Domain already registered”)가 반환됩니다.

DNS 제공업체별 가이드

Cloudflare

AWS Route 53

Vercel

Namecheap

GoDaddy

Google Domains / Squarespace

DigitalOcean

Hetzner

막히셨나요? 문제 해결을 참고하세요.