SDK

Domain

`domains.list`, `get` và `update`.

Mọi phương thức

usage.ts

const domains = await openemail.domains.list()const domain = await openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') console.log(domain.receiving.verified, domain.sending.status)for (const address of domain.addresses) console.log(address.address, address.enabled) const updated = await openemail.domains.update(domain.id, { trackingHost: 'links.acme.com' })console.log(updated.tracking.status, updated.tracking.record?.name, updated.tracking.record?.value) await openemail.domains.update(domain.id, { trackingHost: null })

Nhận thư và gửi thư là hai thực tế độc lập và được trả về thành hai object. receiving.verified nghĩa là MX của domain đưa thư về đây và bản ghi xác minh quyền sở hữu đã được công bố. sending báo cáo kết quả kiểm tra ký thư đi: status là verified, pending, failed, no_identity hoặc unknown, còn canSend cho biết một lần gửi từ domain này có được chấp nhận ngay lúc này hay không. Một kết luận tiêu cực cũ hơn một ngày được coi là chưa xác định chứ không phải từ chối, nên hãy rẽ nhánh theo canSend chứ không theo status.

update đặt, kiểm tra lại hoặc gỡ bỏ tên miền tracking riêng của domain, là một subdomain chẳng hạn links.acme.com, và phân giải ra cùng DomainDetailResource như get. tracking báo cáo nó trên mọi lần đọc. Cho tới khi có một lần kiểm tra đạt, tracking.status là pending và các liên kết được theo dõi cùng pixel theo dõi lượt mở vẫn dùng host OpenEmail mặc định. Khi đã đạt, nó là active và thư mới từ domain dùng tên miền tracking cho cả hai.

get còn liệt kê các địa chỉ trên domain. addresses.list() là lệnh gọi liên quan: mọi địa chỉ mà CHÍNH KEY NÀY được phép đặt vào header From, vốn hẹp hơn.

Tham số: domains.get

domainIdstringbắt buộc: Id lấy từ `domains.list`, là UUID được tạo khi thêm domain, không phải hostname, nên `get('example.com')` không tìm thấy gì. Việc tra cứu được giới hạn theo connection của key cũng như theo id, nên domain của workspace khác trả về 404 chứ không phải 403.

Tham số: domains.update

idstringbắt buộc: Cùng domain id mà `get` nhận. Scope cần có là `domains:write`.
patch.trackingHoststring | nullbắt buộc: Một subdomain của domain, tối đa 512 ký tự, chẳng hạn `links.acme.com`. Giá trị được cắt khoảng trắng và chuyển về chữ thường, đồng thời `https://` hoặc `http://` ở đầu, phần path và dấu chấm ở cuối đều bị loại bỏ. Giá trị mới được xác thực, lưu và kiểm tra trong cùng lệnh gọi. Nếu truyền đúng giá trị domain đang có thì bước kiểm tra chạy lại, trừ khi lần trước cách đây chưa tới 30 giây. `null` hoặc chuỗi rỗng sẽ gỡ bỏ tên miền tracking.

Một host bị từ chối sẽ ném ra OpenEmailApiError với trackingHost trong param: 422 invalid_tracking_host cho tên không dùng được, chẳng hạn tên nằm ngoài domain; 409 domain_not_verified cho host mới khi receiving.verified còn là false và bản ghi TXT _openemail-challenge của domain chưa được công bố; và 409 tracking_host_in_use cho tên mà domain khác đã dùng, hoặc khi tên miền tracking do một máy chủ OpenEmail khác quản lý. Key bị giới hạn theo các địa chỉ cụ thể nhận 422 capability_unsupported, vì tên miền tracking áp dụng cho mọi địa chỉ trên domain.

Phản hồi: DomainDetailResource

object'domain': Luôn là chuỗi `domain`, trên các dòng của `list` cũng như trên object này.
idstring: UUID của domain. Ổn định suốt vòng đời bản ghi, và là định danh duy nhất mà các lệnh gọi domain khác chấp nhận.
domainstring: Hostname trần, chữ thường: `example.com`. Duy nhất trên toàn sản phẩm, mỗi domain một chủ sở hữu, nên hai workspace không thể cùng nhận một domain.
receiving.verifiedboolean: True khi DNS cho thấy MX của domain trỏ tới một host đưa thư về đây và, nếu bản ghi có challenge token, bản ghi TXT `_openemail-challenge` tương ứng cũng đã có. Riêng MX không chứng minh được gì, vì mọi domain mà chúng tôi nhận thư đều công bố cùng các hostname đó; đó là lý do token tồn tại, và là lý do cờ này là điều kiện mà quá trình nhận thư kiểm tra trước khi chấp nhận thư.
receiving.verifiedAtstring | null: Thời điểm xác minh đạt, ISO-8601. Null khi chưa đạt, và `verified` được suy ra từ chính cột này, nên hai trường không bao giờ mâu thuẫn.
receiving.catchAllboolean: Có chấp nhận mọi local-part hay không. Bật mặc định cho các domain được thêm từ khi quy tắc này có hiệu lực; khi tắt, chỉ các địa chỉ đã khai báo trên domain được chấp nhận và các địa chỉ còn lại bị từ chối ở bước SMTP, nên người gửi nhận được thư báo trả lại thay vì im lặng.
receiving.lastCheckedAtstring | null: Thời điểm DNS được truy vấn về domain này lần cuối. Null nghĩa là chưa từng kiểm tra, điều này rất khác với một lần thất bại đối với người vừa thêm domain một phút trước. Endpoint này trả về kết quả đã lưu, không bao giờ tự chạy kiểm tra.
receiving.errorstring | null: Lý do lần kiểm tra gần nhất không đạt, diễn đạt bằng lời mà chủ sở hữu có thể làm theo: `No MX records yet. DNS changes can take a few minutes to spread.` là một ví dụ điển hình. Null khi đã đạt, và được lưu lại chứ không suy ra, để lần tải lại trang và lần kiểm tra định kỳ đều báo cùng một nội dung.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': Trạng thái ký thư đi theo lần kiểm tra gần nhất. Đọc từ kết quả kiểm tra đã lưu chứ không kiểm tra lại trên request này, nên `sending.checkedAt` cho biết nó cũ đến mức nào.
sending.canSendboolean: Một lần gửi từ domain này có được chấp nhận ngay lúc này hay không. Một kết luận tiêu cực cũ hơn một ngày được coi là chưa xác định chứ không phải từ chối, nên trường này có thể là true trong khi `status` là `pending`. Hãy rẽ nhánh theo trường này trước khi gửi: false nghĩa là `emails.send` từ domain này bị từ chối với 409 `domain_not_sendable`.
sending.checkedAtstring | null: Thời điểm trạng thái ký thư được kiểm tra lần cuối, ISO-8601. Null nghĩa là chưa từng kiểm tra, điều này rất khác với một lần thất bại.
sending.errorstring | null: Lỗi ký thư gần nhất, diễn đạt bằng lời, hoặc null khi đã đạt.
sending.notestring: Một trong năm câu, chọn theo `sending.status`, giải thích ý nghĩa của trạng thái đó bằng lời mà chủ domain có thể làm theo. Là văn bản cho người đọc. Hãy rẽ nhánh theo `sending.canSend` chứ không theo trường này.
trackingDomainTracking: Tên miền tracking riêng của domain, trên các dòng của `list` cũng như trên object này, và là thứ mà `update` thay đổi.
tracking.hoststring | null: Tên miền tracking, chẳng hạn `links.acme.com`, hoặc null khi chưa đặt.
tracking.status'none' | 'pending' | 'active' | 'failed': `none` nghĩa là chưa đặt tên miền tracking, `pending` nghĩa là nó chưa từng đạt lần kiểm tra nào, `active` nghĩa là thư mới đang dùng nó, và `failed` nghĩa là nó từng đạt nhưng sau đó đã ngừng được sử dụng. Một host đang active sẽ ngừng được dùng sau ba lần kiểm tra thất bại liên tiếp, hoặc khi lần kiểm tra đạt gần nhất đã cũ hơn 2 giờ.
tracking.activeboolean: True khi và chỉ khi `status` là `active`, tức là khi các liên kết được theo dõi và pixel theo dõi lượt mở trong thư mới từ domain dùng host này.
tracking.targetstring: Địa chỉ mà bản ghi CNAME trỏ tới, được chuẩn bị riêng cho tên miền tracking này. Là chuỗi rỗng khi `host` là null, và khi địa chỉ cho host mới vẫn đang được chuẩn bị.
tracking.record{ type: 'CNAME'; name: string; value: string } | null: Bản ghi cần công bố, có tên là `host` và giá trị là `target`. Null khi không có tên miền tracking, và khi địa chỉ cho host mới vẫn đang được chuẩn bị.
tracking.checkedAtstring | null: Thời điểm host được kiểm tra lần cuối, ISO-8601. Null cho tới lần kiểm tra đầu tiên.
tracking.verifiedAtstring | null: Thời điểm lần kiểm tra đạt gần nhất, ISO-8601. Null với host chưa từng đạt.
tracking.errorstring | null: Kết quả của lần kiểm tra gần nhất, diễn đạt bằng lời mà chủ domain có thể làm theo. Null khi lần kiểm tra gần nhất đạt hoặc chưa chạy lần nào. Một host đã trượt một hoặc hai lần kiểm tra vẫn là `active` và mang lý do ở đây.
addressesArray<{ address: string; enabled: boolean }>: Mọi dòng địa chỉ trên domain, đây là thứ `get` có thêm so với một dòng của `list`. Nó bao gồm cả các dòng do quá trình nhận thư tự ghi dưới chế độ catch-all, và các dòng đó ngừng được chấp nhận ngay khi catch-all bị tắt, nên mảng này không phải là danh sách những địa chỉ sẽ nhận thư.
addresses[].addressstring: Địa chỉ đầy đủ, được dựng lại từ local-part đã lưu và hostname rồi chuyển về chữ thường, nên luôn khớp với `domain` ở trên thay vì lệch khỏi nó.
addresses[].enabledboolean: False sẽ vô hiệu hóa địa chỉ, và địa chỉ bị vô hiệu hóa bị từ chối ngay cả khi catch-all đang bật. Mọi dòng đều được liệt kê bất kể trạng thái, nên hãy lọc theo trường này thay vì coi mảng là tập các địa chỉ đang hoạt động.
createdAtstring: Thời điểm dòng domain được thêm, ISO-8601. Không phải thời điểm xác minh: đó là `receiving.verifiedAt`, có thể là null trong khi trường này đã có giá trị.