커스텀 도메인

자체 브랜드로 이메일을 보내고 수신 준비 상태를 별도로 추적하세요. 기본 @agentsend.io 대신 agent@yourdomain.com과 같은 주소로 수신함을 만들려면 도메인을 추가하세요.

개요

기본적으로 생성하는 모든 수신함은 공유 @agentsend.io 도메인에서 무작위로 생성된 주소를 받습니다. 시작하기에 좋지만, 에이전트가 자체 브랜드로 이메일을 보내려면 커스텀 도메인을 추가할 수 있습니다.

도메인이 확인되면 해당 도메인에 수신함을 만들고 support@yourdomain.com이나 assistant@yourdomain.com과 같은 주소에서 온 것처럼 보이는 이메일을 보낼 수 있습니다. 수신자는 From 헤더에서 도메인을 봅니다. 수신 답장은 도메인이 사용하는 MX 라우팅을 따르므로, 수신 메일을 AgentSend로 전달하려는 경우에만 MX를 AgentSend로 지정하세요.

ℹ

커스텀 도메인은 도메인 등록 기관(Cloudflare, Route 53, Namecheap 등)에 DNS 레코드를 추가해야 합니다. 검증 프로세스는 전송을 허용하기 전에 해당 레코드가 전파되었는지 확인합니다.

도메인 추가

/domains로 POST 요청을 보내 AgentSend에 도메인을 등록합니다. 응답에는 추가해야 할 DNS 레코드가 포함됩니다.

javascript

const res = await fetch("https://api.agentsend.io/domains", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    domain: "yourdomain.com",
  }),
});

const domain = await res.json();
console.log(domain.id);               // "dom_..."
console.log(domain.sendingStatus);   // "pending"
console.log(domain.receivingStatus); // "pending"
console.log(domain.dnsRecords);      // combined DNS records to add

응답 예시

json

{
  "id": "dom_01hx4r2kt9fzv8s3n",
  "domain": "yourdomain.com",
  "sendingStatus": "pending",
  "receivingStatus": "pending",
  "verificationStatus": "pending",
  "createdAt": "2025-04-16T10:00:00.000Z",
  "dnsRecords": [
    {
      "type": "TXT",
      "host": "_amazonses.yourdomain.com",
      "value": "verification-token"
    },
    {
      "type": "CNAME",
      "host": "dkim-a._domainkey.yourdomain.com",
      "value": "dkim-a.dkim.amazonses.com"
    },
    {
      "type": "MX",
      "host": "yourdomain.com",
      "value": "mx.agentsend.io",
      "priority": 10
    }
  ]
}

DNS 설정

도메인을 추가한 후 DNS 제공업체로 이동해 dnsRecords에 반환된 레코드를 추가하세요. TXT 및 CNAME 레코드는 발신자 신원과 DKIM 서명을 검증합니다. MX 레코드는 AgentSend가 도메인의 수신 메일을 받기를 원할 때만 필요합니다.

타입	호스트	값	용도
`MX`	`yourdomain.com`	`mx.agentsend.io` (priority 10)	도메인의 수신 이메일을 AgentSend 메일 서버로 라우팅하여 답장이 에이전트 수신함에 도착합니다.
`TXT` (verification)	`_amazonses.yourdomain.com`	SES 검증 토큰	Amazon SES에서 발신 도메인을 제어한다는 것을 확인합니다.
`CNAME` (DKIM)	`<token>._domainkey.yourdomain.com`	`<token>.dkim.amazonses.com`	발신 메시지를 암호화 서명하여 수신자가 해당 메시지가 도메인의 권한으로 AgentSend에 의해 전송되었음을 검증할 수 있게 합니다.

💡

DNS 변경은 일반적으로 몇 분 안에 전파되지만, 드물게 최대 48시간까지 걸릴 수 있습니다. 터미널에서 dig TXT agentsend._domainkey.yourdomain.com을 실행해 DKIM 레코드가 활성화되었는지 확인할 수 있습니다.

⚠

도메인에 이미 MX 레코드가 있으면 AgentSend의 MX 레코드를 추가하면 해당 도메인의 모든 수신 이메일이 AgentSend로 라우팅됩니다. 기존 메일 라우팅을 유지하려면 서브도메인(예: mail.yourdomain.com)을 사용하세요.

검증

DNS 레코드를 추가한 후 POST /domains/{id}/verify를 호출해 검증 확인을 트리거합니다. AgentSend는 발신자 검증을 새로 고치고 수신 메일을 위해 MX가 AgentSend를 가리키는지 별도로 확인합니다.

javascript

const res = await fetch(
  `https://api.agentsend.io/domains/${domain.id}/verify`,
  {
    method: "POST",
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

const result = await res.json();
console.log(result.sendingStatus);   // "verified" | "pending_dkim" | "failed"
console.log(result.receivingStatus); // "verified" | "pending" | "failed"

상태 흐름

sendingStatus와 receivingStatus는 별도로 추적됩니다. verificationStatus는 sendingStatus의 하위 호환 별칭으로 유지됩니다.

상태	의미
`pending`	도메인이 등록되었지만 검증이 아직 시도되지 않았습니다. DNS 레코드가 확인되지 않았습니다.
`pending_dkim`	도메인 소유권이 검증되었지만 DKIM 레코드가 아직 표시되지 않습니다. 몇 분 기다린 후 재시도하세요.
`verified`	필요한 모든 DNS 레코드가 확인되었습니다. 도메인은 이메일 발송에 사용할 준비가 되었습니다. 수신은 여전히 도메인의 MX 레코드가 가리키는 곳에 따라 다릅니다.
`failed`	검증이 실패했습니다. 필요한 레코드를 하나 이상 찾을 수 없습니다. DNS 제공업체에 레코드가 올바르게 입력되었는지 확인한 후 재시도하세요.

ℹ

/domains/{id}/verify는 필요한 만큼 여러 번 호출할 수 있습니다. 폴링해도 안전합니다 — 예를 들어 상태가 verified가 될 때까지 30초마다 호출할 수 있습니다.

도메인 속성

도메인 객체는 다음 필드를 갖습니다:

속성	타입	설명
`id`	string	도메인의 고유 식별자. `dom_` 접두사.
`domain`	string	도메인 생성 시 제공된 도메인 이름 (예: `yourdomain.com`).
`sendingStatus`	string	현재 발신자 검증 상태: `pending`, `pending_dkim`, `verified`, 또는 `failed`.
`receivingStatus`	string	MX 기반 현재 수신 라우팅 상태: `pending`, `verified`, 또는 `failed`.
`verificationStatus`	string	`sendingStatus`의 하위 호환 별칭.
`dnsRecords`	array	DNS 제공업체에 추가해야 할 DNS 레코드 객체 배열. 각 레코드는 `type`, `host`, `value`, 그리고 선택적으로 `priority`를 갖습니다.
`createdAt`	string (ISO 8601)	AgentSend에 도메인이 등록된 시각.

커스텀 도메인에서 수신함 만들기

도메인이 verified되면 수신함을 만들 때 id를 domainId로 전달하세요. 수신함 주소는 @agentsend.io 대신 도메인을 사용합니다.

javascript

const res = await fetch("https://api.agentsend.io/inboxes", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    displayName: "Support Agent",
    username: "support",       // becomes support@yourdomain.com
    domainId: "dom_01hx4r2kt9fzv8s3n",
  }),
});

const inbox = await res.json();
console.log(inbox.address); // "support@yourdomain.com"

💡

username 필드는 이메일 주소의 로컬 부분을 설정합니다. 생략하면 AgentSend가 무작위 값을 생성합니다. 동일한 검증된 도메인에서 필요한 만큼 수신함을 만들 수 있습니다.

도메인 삭제

/domains/{id}로 DELETE 요청을 보내 도메인을 제거합니다.

javascript

await fetch(`https://api.agentsend.io/domains/${domain.id}`, {
  method: "DELETE",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});

⚠

도메인 삭제는 영구적입니다. 도메인과 연결된 모든 수신함은 이메일 주소를 잃고 더 이상 이메일을 송수신할 수 없습니다. 해당 수신함의 기존 메시지는 유지되지만 새 메일은 전송될 수 없습니다. 이 작업은 취소할 수 없습니다.

← 이전 웹훅 다음 → 첨부파일