Tên Miền Tùy Chỉnh

Gửi email từ thương hiệu của bạn và theo dõi sẵn sàng nhận riêng. Thêm một tên miền để tạo hộp thư với địa chỉ như agent@yourdomain.com thay vì @agentsend.io mặc định.

Tổng Quan

Theo mặc định, mỗi hộp thư bạn tạo có địa chỉ được sinh ngẫu nhiên trên tên miền chia sẻ @agentsend.io. Điều này tuyệt vời để bắt đầu, nhưng nếu bạn muốn agent gửi email từ thương hiệu riêng, bạn có thể thêm tên miền tùy chỉnh.

Sau khi tên miền được xác minh, bạn có thể tạo hộp thư trên đó và gửi email hiển thị xuất phát từ các địa chỉ như support@yourdomain.com hoặc assistant@yourdomain.com. Người nhận thấy tên miền của bạn trong header From. Các phản hồi đến sẽ theo bất kỳ định tuyến MX nào tên miền của bạn sử dụng, vì vậy chỉ trỏ MX đến AgentSend nếu bạn muốn email đến được giao vào AgentSend.

Tên miền tùy chỉnh yêu cầu thêm bản ghi DNS vào nhà đăng ký tên miền của bạn (Cloudflare, Route 53, Namecheap, v.v.). Quá trình xác minh kiểm tra các bản ghi đó đã lan truyền trước khi cho phép gửi.

Thêm Tên Miền

Đăng ký tên miền với AgentSend bằng cách gửi yêu cầu POST đến /domains. Phản hồi bao gồm các bản ghi DNS bạn cần thêm.

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);      // các bản ghi DNS cần thêm

Ví dụ phản hồi

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
    }
  ]
}

Thiết Lập DNS

Sau khi thêm tên miền, truy cập nhà cung cấp DNS và thêm các bản ghi được trả về trong dnsRecords. Các bản ghi TXT và CNAME xác minh danh tính người gửi và ký DKIM. Bản ghi MX chỉ cần nếu bạn cũng muốn AgentSend nhận email đến cho tên miền.

Kiểu Host Giá trị Mục đích
MX yourdomain.com mx.agentsend.io (priority 10) Định tuyến email đến cho tên miền của bạn đến máy chủ email của AgentSend, để các phản hồi đến hộp thư của agent.
TXT (xác minh) _amazonses.yourdomain.com Token xác minh SES Xác nhận bạn kiểm soát tên miền gửi trong Amazon SES.
CNAME (DKIM) <token>._domainkey.yourdomain.com <token>.dkim.amazonses.com Ký mật mã các tin nhắn gửi đi để người nhận có thể xác minh chúng được AgentSend gửi với sự ủy quyền từ tên miền của bạn.
💡

Thay đổi DNS thường lan truyền trong vài phút, nhưng trong trường hợp hiếm có thể mất tới 48 giờ. Bạn có thể chạy dig TXT agentsend._domainkey.yourdomain.com từ terminal để kiểm tra bản ghi DKIM đã sống hay chưa.

Nếu tên miền của bạn đã có bản ghi MX, thêm bản ghi MX của AgentSend sẽ định tuyến tất cả email đến cho tên miền đó vào AgentSend. Dùng subdomain (ví dụ mail.yourdomain.com) nếu bạn cần giữ lại định tuyến email hiện có.

Xác Minh

Sau khi bạn đã thêm các bản ghi DNS, kích hoạt kiểm tra xác minh bằng cách gọi POST /domains/{id}/verify. AgentSend làm mới xác minh người gửi và kiểm tra riêng liệu MX của bạn có trỏ đến AgentSend cho email đến hay không.

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"

Luồng trạng thái

sendingStatusreceivingStatus được theo dõi riêng. verificationStatus vẫn là bí danh tương thích ngược của sendingStatus.

Trạng thái Ý nghĩa
pending Tên miền đã được đăng ký nhưng xác minh chưa được thực hiện. Chưa có bản ghi DNS nào được kiểm tra.
pending_dkim Sở hữu tên miền đã xác minh, nhưng các bản ghi DKIM chưa xuất hiện. Chờ vài phút rồi thử lại.
verified Tất cả bản ghi DNS bắt buộc đã được xác nhận. Tên miền sẵn sàng để gửi email. Việc nhận vẫn phụ thuộc vào nơi bản ghi MX của tên miền trỏ đến.
failed Xác minh thất bại. Một hoặc nhiều bản ghi bắt buộc không được tìm thấy. Kiểm tra các bản ghi đã được nhập chính xác vào nhà cung cấp DNS và thử lại.

Bạn có thể gọi /domains/{id}/verify nhiều lần tùy ý. Có thể poll an toàn — ví dụ, gọi mỗi 30 giây cho đến khi trạng thái trở thành verified.

Thuộc Tính Tên Miền

Một đối tượng tên miền có các trường sau:

Thuộc tính Kiểu Mô tả
id string Định danh duy nhất cho tên miền, với tiền tố dom_.
domain string Tên miền như đã cung cấp khi tên miền được tạo, ví dụ yourdomain.com.
sendingStatus string Trạng thái xác minh người gửi hiện tại: pending, pending_dkim, verified, hoặc failed.
receivingStatus string Trạng thái định tuyến đến hiện tại dựa trên MX: pending, verified, hoặc failed.
verificationStatus string Bí danh tương thích ngược của sendingStatus.
dnsRecords array Mảng các đối tượng bản ghi DNS cần thêm vào nhà cung cấp DNS. Mỗi bản ghi có type, host, value, và tùy chọn priority.
createdAt string (ISO 8601) Dấu thời gian khi tên miền được đăng ký với AgentSend.

Tạo Hộp Thư Trên Tên Miền Tùy Chỉnh

Khi một tên miền là verified, truyền id của nó làm domainId khi tạo hộp thư. Địa chỉ hộp thư sẽ dùng tên miền của bạn thay vì @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",       // trở thành support@yourdomain.com
    domainId: "dom_01hx4r2kt9fzv8s3n",
  }),
});

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

Trường username đặt phần local của địa chỉ email. Nếu bỏ qua, AgentSend tự sinh ngẫu nhiên. Bạn có thể tạo bao nhiêu hộp thư tùy ý trên cùng tên miền đã xác minh.

Xóa Tên Miền

Xóa một tên miền bằng yêu cầu DELETE đến /domains/{id}.

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

Xóa tên miền là vĩnh viễn. Tất cả hộp thư gắn với tên miền sẽ mất địa chỉ email và không thể gửi hay nhận email nữa. Các tin nhắn hiện có trong các hộp thư đó được giữ lại, nhưng email mới không thể giao. Hành động này không thể hoàn tác.