도메인

발신 및 수신 준비를 별도로 관리하며 커스텀 도메인을 추가하고 관리하세요. 발신자 신원 레코드를 검증하고 MX 라우팅을 독립적으로 확인합니다.

개요

기본적으로 수신함은 @agentsend.io에서 보냅니다. 자체 도메인을 추가하면 agent@yourdomain.com과 같은 주소에서 보낼 수 있어 전송 가능성과 브랜드 신뢰도가 향상됩니다.

도메인을 추가한 후 AgentSend는 발신 및 수신을 위한 별도의 DNS 레코드를 반환합니다. 게시되면 verify 엔드포인트를 호출해 두 상태를 모두 새로 고칩니다: sending은 SES 발신자 검증과 DKIM을 확인하고, receiving은 도메인의 MX가 AgentSend를 가리키는지 확인합니다.

ℹ

모든 요청에는 x-api-key 헤더가 필요합니다. 대시보드에서 키를 받으세요.

Domain 객체

모든 도메인 엔드포인트는 Domain 객체(또는 객체 배열)를 반환합니다.

Domain object

{
  "id":                 "dom_01hxyz...",          // UUID
  "domain":             "mail.yourdomain.com",
  "sendingStatus":      "pending",              // pending | pending_dkim | verified | failed
  "receivingStatus":    "pending",              // pending | verified | failed
  "verificationStatus": "pending",              // backward-compatible alias of sendingStatus
  "sendingDnsRecords": [
    {
      "type":  "TXT",
      "name":  "_amazonses.mail.yourdomain.com",
      "value": "verification-token"
    },
    {
      "type":  "CNAME",
      "name":  "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1.dkim.amazonses.com"
    }
  ],
  "receivingDnsRecords": [
    {
      "type":  "MX",
      "name":  "mail.yourdomain.com",
      "value": "mx.agentsend.io",
      "priority": 10
    }
  ],
  "dnsRecords": [
    {
      "type":  "TXT",
      "name":  "_amazonses.mail.yourdomain.com",
      "value": "verification-token"
    }
  ],
  "sendingVerifiedAt": null,
  "receivingVerifiedAt": null,
  "createdAt": "2024-11-01T09:00:00Z"
}

필드	타입	설명
`id`	string	고유 도메인 식별자 (UUID).
`domain`	string	추가한 도메인 또는 서브도메인.
`sendingStatus`	string	발신자 검증 상태. `pending`, `pending_dkim`, `verified`, `failed`.
`receivingStatus`	string	MX 기반 수신 라우팅 상태. `pending`, `verified`, `failed`.
`verificationStatus`	string	`sendingStatus`의 하위 호환 별칭.
`sendingDnsRecords`	array	발신 검증 및 DKIM 서명에 필요한 DNS 레코드.
`receivingDnsRecords`	array	AgentSend가 도메인의 수신 메일을 받도록 하려면 필요한 DNS 레코드.
`dnsRecords`	array	편의를 위한 발신 및 수신 레코드의 결합 목록.
`sendingVerifiedAt`	string \| null	발신 검증이 마지막으로 `verified`에 도달한 시각.
`receivingVerifiedAt`	string \| null	MX 검증이 마지막으로 `verified`에 도달한 시각.
`createdAt`	string (ISO 8601)	도메인이 추가된 시각.

POST /domains

커스텀 도메인을 추가합니다. 검증 전에 게시해야 하는 DNS 레코드를 포함한 새 Domain 객체를 반환합니다.

요청 본문

파라미터	타입	설명
`domain` 필수	string	추가할 도메인 또는 서브도메인 (예: `mail.yourdomain.com`).

curl

curl -X POST https://api.agentsend.io/domains \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.yourdomain.com"}'

Response `201 Created`

json

{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "pending",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail.yourdomain.com",
      "value": "v=spf1 include:spf.agentsend.io ~all"
    },
    {
      "type": "CNAME",
      "name": "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1._domainkey.agentsend.io"
    },
    {
      "type": "CNAME",
      "name": "agsend2._domainkey.mail.yourdomain.com",
      "value": "agsend2._domainkey.agentsend.io"
    }
  ],
  "createdAt": "2024-11-01T09:00:00Z"
}

💡

반환된 모든 dnsRecords를 DNS 등록 기관에 게시한 후 POST /domains/{id}/verify를 호출해 도메인을 활성화하세요.

GET /domains

계정의 모든 도메인을 현재 검증 상태와 함께 나열합니다.

파라미터

쿼리 파라미터 없음.

curl

curl https://api.agentsend.io/domains \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response `200 OK`

json

{
  "data": [
    {
      "id": "dom_01hxyz4k9s2n3p7q",
      "domain": "mail.yourdomain.com",
      "verificationStatus": "verified",
      "dnsRecords": [ /* ... */ ],
      "createdAt": "2024-11-01T09:00:00Z"
    },
    {
      "id": "dom_01hzab8m3t4r2w9c",
      "domain": "outbound.acme.io",
      "verificationStatus": "pending",
      "dnsRecords": [ /* ... */ ],
      "createdAt": "2024-11-15T14:23:00Z"
    }
  ]
}

GET /domains/{id}

ID로 단일 도메인을 전체 DNS 레코드와 현재 검증 상태와 함께 가져옵니다.

경로 파라미터

파라미터	타입	설명
`id` 필수	string (uuid)	가져올 도메인의 ID.

curl

curl https://api.agentsend.io/domains/dom_01hxyz4k9s2n3p7q \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response `200 OK`

json

{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "verified",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail.yourdomain.com",
      "value": "v=spf1 include:spf.agentsend.io ~all"
    },
    {
      "type": "CNAME",
      "name": "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1._domainkey.agentsend.io"
    },
    {
      "type": "CNAME",
      "name": "agsend2._domainkey.mail.yourdomain.com",
      "value": "agsend2._domainkey.agentsend.io"
    }
  ],
  "createdAt": "2024-11-01T09:00:00Z"
}

DELETE /domains/{id}

계정에서 도메인을 영구적으로 삭제합니다. 이 도메인을 사용하는 수신함은 @agentsend.io 주소로 되돌아갑니다. 이 작업은 취소할 수 없습니다.

경로 파라미터

파라미터	타입	설명
`id` 필수	string (uuid)	삭제할 도메인의 ID.

curl

curl -X DELETE https://api.agentsend.io/domains/dom_01hxyz4k9s2n3p7q \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response `204 No Content`

성공 시 빈 본문을 반환합니다.

⚠

도메인 삭제는 등록 기관에서 DNS 레코드를 제거하지 않습니다. 삭제 후 수동으로 정리해야 합니다.

POST /domains/{id}/verify

새로운 도메인 준비 확인을 트리거합니다. AgentSend는 SES 및 DKIM에서 발신자 검증을 업데이트한 다음 도메인의 MX가 수신 메일을 위해 AgentSend를 가리키는지 별도로 확인합니다.

경로 파라미터

파라미터	타입	설명
`id` 필수	string (uuid)	검증할 도메인의 ID.

curl

curl -X POST https://api.agentsend.io/domains/dom_01hxyz4k9s2n3p7q/verify \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response `200 OK`

업데이트된 Domain 객체를 반환합니다. 최신 결과를 확인하려면 sendingStatus와 receivingStatus를 확인하세요.

json — verified

{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "verified",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail.yourdomain.com",
      "value": "v=spf1 include:spf.agentsend.io ~all"
    },
    {
      "type": "CNAME",
      "name": "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1._domainkey.agentsend.io"
    },
    {
      "type": "CNAME",
      "name": "agsend2._domainkey.mail.yourdomain.com",
      "value": "agsend2._domainkey.agentsend.io"
    }
  ],
  "createdAt": "2024-11-01T09:00:00Z"
}

json — pending_dkim (ownership ok, DKIM not yet propagated)

{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "pending_dkim",
  "dnsRecords": [ /* ... */ ],
  "createdAt": "2024-11-01T09:00:00Z"
}

ℹ

DNS 변경은 전 세계에 전파되는 데 최대 48시간이 걸릴 수 있습니다. 검증이 pending_dkim 또는 failed를 반환하면 몇 분 기다린 후 verify를 다시 호출하세요.

← 이전 API: 웹훅 다음 → API: 계정

도메인

개요

Domain 객체

POST /domains

요청 본문

Response 201 Created

GET /domains

파라미터

Response 200 OK

GET /domains/{id}

경로 파라미터

Response 200 OK

DELETE /domains/{id}

경로 파라미터

Response 204 No Content

POST /domains/{id}/verify

경로 파라미터

Response 200 OK

Response `201 Created`

Response `200 OK`

Response `200 OK`

Response `204 No Content`

Response `200 OK`