Bỏ qua tới phần tài liệu
API

Cập nhật tên miền

Thiết lập, kiểm tra lại hoặc gỡ bỏ tên miền theo dõi tùy chỉnh và tên miền tệp tùy chỉnh của tên miền, hai thứ duy nhất của tên miền mà API này có thể thay đổi.

PATCHapi.openemail.uk/domains/{id}

Chạy lệnh gọi thật với không gian làm việc của bạn, bằng khóa của chính bạn.

PATCH /domains/{id}

Thiết lập, kiểm tra lại hoặc gỡ bỏ tên miền theo dõi tùy chỉnh và tên miền tệp tùy chỉnh của tên miền, hai thứ duy nhất của tên miền mà API này có thể thay đổi.

Yêu cầu

Mỗi tên miền có thể có một tên miền theo dõi tùy chỉnh và một tên miền tệp tùy chỉnh, mỗi cái là một tên miền con do bạn chọn, chẳng hạn links.acme.comfiles.acme.com, ngay khi tên miền đã được xác minh hoặc bản ghi TXT _openemail-challenge của nó đã được công bố. Tên miền chưa cần phải đang nhận thư. Việc thiết lập một tên sẽ chuẩn bị một địa chỉ riêng cho tên đó, được trả về trong target, và record là bản ghi CNAME trỏ tên đó tới địa chỉ này. Khi một lần kiểm tra thành công, liên kết được theo dõi và pixel theo dõi lượt mở trong thư mới từ tên miền sẽ dùng https://links.acme.com/t/..., và liên kết tải xuống cho các tệp gửi từ tên miền sẽ dùng https://files.acme.com/f/..., thay cho host mặc định.

Tham số

trackingHoststring | null
Tên miền con dùng cho liên kết được theo dõi và pixel theo dõi lượt mở, tối đa 512 ký tự. Giá trị được cắt khoảng trắng và chuyển thành chữ thường, đồng thời tiền tố `https://` hoặc `http://`, đường dẫn và dấu chấm ở cuối bị loại bỏ trước khi kiểm tra. Giá trị mới sẽ thay thế tên miền theo dõi hiện tại, giá trị hiện tại sẽ chạy lại lần kiểm tra, `null` hoặc chuỗi rỗng sẽ gỡ bỏ nó, còn bỏ qua trường này thì giữ nguyên.
storageHoststring | null
Tên miền con dùng cho liên kết tải tệp xuống, được chuẩn hóa theo cùng cách và cũng giới hạn 512 ký tự. Giá trị mới sẽ thay thế tên miền tệp hiện tại, giá trị hiện tại sẽ chạy lại lần kiểm tra, `null` hoặc chuỗi rỗng sẽ gỡ bỏ nó, còn bỏ qua trường này thì giữ nguyên.

Phần thân yêu cầu nghiêm ngặt về key nhưng linh hoạt về số lượng key bạn gửi. Mọi key khác ngoài trackingHoststorageHost đều trả về 422 unknown_parameter, còn phần thân không chứa key nào trong hai key đó là thao tác không làm gì, trả về 200 cùng tên miền ở trạng thái hiện tại. Có thể gửi cả hai trong một lệnh gọi, và chúng được áp dụng theo thứ tự, trackingHost trước: một trackingHost bị từ chối sẽ dừng lệnh gọi trước khi storageHost được xử lý, còn một storageHost bị từ chối vẫn giữ nguyên thay đổi trackingHost đã thực hiện. Hãy gửi riêng từng key khi mỗi thay đổi cần đứng độc lập.

Thiết lập tên miền theo dõi và tên miền tệp

Cần domains:write. Mỗi host được kiểm tra tính hợp lệ, lưu và kiểm tra trong cùng một lệnh gọi, nên phản hồi đã chứa sẵn kết quả của lần kiểm tra đầu tiên đó. Phần thân phản hồi giống với GET /domains/{id}.

curl
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \  -d '{ "trackingHost": "links.acme.com", "storageHost": "files.acme.com" }'
Phản hồi
{  "object": "domain",  "id": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f",  "domain": "acme.com",  "receiving": {    "verified": true,    "verifiedAt": "2026-08-14T10:02:00.000Z",    "catchAll": false,    "lastCheckedAt": "2026-08-29T06:00:00.000Z",    "error": null  },  "sending": {    "status": "verified",    "canSend": true,    "checkedAt": "2026-08-29T06:00:00.000Z",    "error": null,    "note": "Mail from this domain is signed and can be sent."  },  "tracking": {    "host": "links.acme.com",    "status": "pending",    "active": false,    "target": "oelinks3f9a1c7e2b8d4a60.edge.openemail.uk",    "record": { "type": "CNAME", "name": "links.acme.com", "value": "oelinks3f9a1c7e2b8d4a60.edge.openemail.uk" },    "checkedAt": "2026-08-29T06:05:12.000Z",    "verifiedAt": null,    "error": "links.acme.com does not resolve yet. Add a CNAME record named links.acme.com with the value oelinks3f9a1c7e2b8d4a60.edge.openemail.uk, then check again."  },  "storage": {    "host": "files.acme.com",    "status": "pending",    "active": false,    "target": "oefiles81c40d6b2f7e9a35.edge.openemail.uk",    "record": { "type": "CNAME", "name": "files.acme.com", "value": "oefiles81c40d6b2f7e9a35.edge.openemail.uk" },    "checkedAt": "2026-08-29T06:05:12.000Z",    "verifiedAt": null,    "error": "files.acme.com does not resolve yet. Add a CNAME record named files.acme.com with the value oefiles81c40d6b2f7e9a35.edge.openemail.uk, then check again."  },  "addresses": [    { "address": "[email protected]", "enabled": true }  ],  "createdAt": "2026-08-14T09:55:11.000Z"}

Công bố tracking.recordstorage.record tại nhà cung cấp DNS của bạn dưới dạng CNAME thông thường, tắt mọi chế độ proxy. Lần kiểm tra sẽ phân giải từng tên, rồi gửi yêu cầu tới https://links.acme.com/t/v/<nonce> hoặc https://files.acme.com/f/v/<nonce> để nhận một phản hồi do OpenEmail ký. Một chuyển hướng sẽ làm lần kiểm tra thất bại, và một proxy đặt trước tên đó cũng có thể gây ra điều tương tự.

Khi bản ghi đã phân giải được, một lần kiểm tra có thể báo rằng tên đó đã trỏ tới OpenEmail và đang chờ được kích hoạt. Đó là lúc chứng chỉ HTTPS của nó đang được cấp, việc này diễn ra ở phía chúng tôi, không cần bạn làm gì và có thể mất một chút thời gian. Khi hoàn tất, lần kiểm tra thành công tiếp theo sẽ đặt status thành active.

Nếu không thể chuẩn bị địa chỉ trong lúc gọi, record là null, target là chuỗi rỗng và error cho biết địa chỉ đang được chuẩn bị. Việc này hoàn tất trong vài phút mà không cần gọi thêm, vì vậy hãy đọc lại tên miền bằng GET /domains/{id} để lấy bản ghi.

Hai tên này độc lập với nhau. Một lệnh gọi chỉ mang một trường sẽ giữ nguyên đối tượng còn lại, nên việc thiết lập tên miền tệp sau này không bao giờ ảnh hưởng tới một tên miền theo dõi đang hoạt động.

Kiểm tra lại hoặc gỡ bỏ

Gửi lại host mà tên miền đang có để chạy kiểm tra ngay thay vì chờ lần kiểm tra theo lịch tiếp theo. Nếu lần kiểm tra gần nhất, dù theo lịch hay không, đã chạy cách đây chưa tới 30 giây, lệnh gọi sẽ trả về trạng thái đã lưu mà không thay đổi. Gửi null trong một trường để gỡ bỏ tên đó, và bỏ qua trường còn lại để giữ nguyên tên mà nó đang có.

curl
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \  -d '{ "trackingHost": null }'
tracking, sau khi gỡ bỏ
{  "host": null,  "status": "none",  "active": false,  "target": "",  "record": null,  "checkedAt": null,  "verifiedAt": null,  "error": null}

Liên kết trong thư đã gửi giữ nguyên host lúc gửi đi, điều này áp dụng cho liên kết tải tệp xuống cũng như cho liên kết được theo dõi. Sau khi bạn gỡ bỏ hoặc thay đổi một tên, các liên kết đó vẫn hoạt động chừng nào bản ghi CNAME cũ còn được giữ. Thiết lập lại một tên có thể tạo ra record khác, vì vậy hãy công bố bản ghi mà phản hồi trả về.

Đối tượng tracking

hoststring | null
Tên miền theo dõi, hoặc null khi tên miền không có.
status'none' | 'pending' | 'active' | 'failed'
`none` nghĩa là chưa thiết lập tên miền theo dõi. `pending` nghĩa là đã thiết lập nhưng chưa từng vượt qua lần kiểm tra nào. `active` nghĩa là thư mới đang dùng nó. `failed` nghĩa là nó từng vượt qua kiểm tra nhưng sau đó đã bị ngừng sử dụng.
activeboolean
Là true khi và chỉ khi `status` là `active`, tức là khi liên kết được theo dõi và pixel theo dõi lượt mở trong thư mới từ tên miền đang dùng host này.
targetstring
Địa chỉ mà bản ghi CNAME trỏ tới, được chuẩn bị riêng cho tên miền theo dõi này. Giá trị là chuỗi rỗng khi `host` là null, và trong lúc địa chỉ cho một host mới vẫn đang được chuẩn bị.
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`. Là null khi không có tên miền theo dõi, và trong lúc địa chỉ cho một host mới vẫn đang được chuẩn bị.
checkedAtstring | null
Thời điểm host được kiểm tra gần nhất, định dạng ISO-8601. Là null cho tới lần kiểm tra đầu tiên.
verifiedAtstring | null
Thời điểm lần kiểm tra thành công gần nhất, định dạng ISO-8601. Là null với host chưa từng vượt qua lần kiểm tra nào.
errorstring | null
Kết quả của lần kiểm tra gần nhất, diễn đạt để chủ sở hữu tên miền có thể xử lý. Là null khi lần kiểm tra gần nhất thành công hoặc chưa có lần nào chạy. Một host thất bại một hoặc hai lần kiểm tra vẫn là `active` và lý do được ghi tại đây.

Đối tượng storage

Tên miền tệp được báo cáo trong storage, với các trường giống hệt tracking. Chỉ có mục đích sử dụng của tên là khác: active ở đó nghĩa là liên kết tải xuống cho các tệp gửi từ tên miền đang trỏ tới nó.

hoststring | null
Tên miền tệp, hoặc null khi tên miền không có.
status'none' | 'pending' | 'active' | 'failed'
`none` nghĩa là chưa thiết lập tên miền tệp. `pending` nghĩa là đã thiết lập nhưng chưa từng vượt qua lần kiểm tra nào. `active` nghĩa là thư mới đang dùng nó. `failed` nghĩa là nó từng vượt qua kiểm tra nhưng sau đó đã bị ngừng sử dụng.
activeboolean
Là true khi và chỉ khi `status` là `active`, tức là khi liên kết tải xuống cho các tệp gửi từ tên miền đang dùng host này.
targetstring
Địa chỉ mà bản ghi CNAME trỏ tới, được chuẩn bị riêng cho tên miền tệp này. Giá trị là chuỗi rỗng khi `host` là null, và trong lúc địa chỉ cho một host mới vẫn đang được chuẩn bị.
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`. Là null khi không có tên miền tệp, và trong lúc địa chỉ cho một host mới vẫn đang được chuẩn bị.
checkedAtstring | null
Thời điểm host được kiểm tra gần nhất, định dạng ISO-8601. Là null cho tới lần kiểm tra đầu tiên.
verifiedAtstring | null
Thời điểm lần kiểm tra thành công gần nhất, định dạng ISO-8601. Là null với host chưa từng vượt qua lần kiểm tra nào.
errorstring | null
Kết quả của lần kiểm tra gần nhất, diễn đạt để chủ sở hữu tên miền có thể xử lý. Là null khi lần kiểm tra gần nhất thành công hoặc chưa có lần nào chạy. Một host thất bại một hoặc hai lần kiểm tra vẫn là `active` và lý do được ghi tại đây.

Cách host được kiểm tra

Cả hai tên được kiểm tra theo cùng một lịch, và mỗi tên được kiểm tra riêng.

  • Một host chưa vượt qua lần kiểm tra nào sẽ được kiểm tra mỗi 2 phút trong giờ đầu tiên, mỗi 10 phút trong ngày đầu tiên, mỗi giờ trong tuần đầu tiên và mỗi 6 giờ sau đó.
  • Một host đang hoạt động được kiểm tra mỗi 10 phút, và một lần kiểm tra thất bại sẽ được thử lại sau 1 phút rồi sau 2 phút.
  • Một host đang hoạt động sẽ ngừng được sử 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 thành công gần nhất đã cách đây hơn 2 giờ. Khi đó thư mới quay lại dùng host mặc định, và status hiển thị failed cho đến khi một lần kiểm tra thành công trở lại. Việc kiểm tra vẫn tiếp tục, giãn cách dần sau mỗi lần và cách nhau tối đa một giờ.

Tên miền theo dõi chỉ phục vụ các đường dẫn theo dõi và tên miền tệp chỉ phục vụ các đường dẫn tải xuống, và mỗi tên miền chỉ phản hồi cho thư được gửi bởi không gian làm việc sở hữu nó.

Lỗi

Trạng tháitypecodeKhi nào
400invalid_request_errormalformed_jsonPhần thân không phải JSON hợp lệ.
403permission_errorinsufficient_scopeKhóa không có domains:write.
404not_found_errorresource_not_foundKhông có tên miền nào với id đó trong không gian làm việc này.
409conflict_errordomain_not_verifiedMột host mới được gửi trong khi receiving.verified là false và bản ghi TXT _openemail-challenge của tên miền chưa được công bố. param là trường chứa host đó, trackingHost hoặc storageHost.
409conflict_errortracking_host_in_useMột tên miền khác đã dùng host này làm tên miền theo dõi, host này đang được dùng làm tên miền tệp, hoặc tên miền theo dõi của tên miền này được quản lý bởi một máy chủ OpenEmail khác. paramtrackingHost.
409conflict_errorstorage_host_in_useBa trường hợp tương tự cho tên miền tệp: một tên miền khác đã dùng host này làm tên miền tệp, host này đang được dùng làm tên miền theo dõi, hoặc tên miền tệp ở đây được quản lý bởi một máy chủ OpenEmail khác. paramstorageHost.
422validation_errorinvalid_tracking_hostHost không phải là hostname hợp lệ, hoặc không được phép: nó phải là tên miền con thực sự của tên miền, và không được là host return path bounce.<domain>, một tên thuộc về OpenEmail hoặc một tên miền đã được thiết lập để nhận thư. paramtrackingHost.
422validation_errorinvalid_storage_hostCùng các quy tắc đó, bị từ chối với tên miền tệp. paramstorageHost.
422validation_errorunknown_parameterMột key trong phần thân khác ngoài trackingHoststorageHost.
422validation_errorinvalid_parameterPhần thân không phải là một JSON object, hoặc một trường có mặt nhưng không phải string cũng không phải null, hoặc dài quá 512 ký tự. Phần thân không chứa trường nào trong hai trường đó không phải là lỗi: nó không thay đổi gì và trả về 200.
422validation_errorcapability_unsupportedKhóa bị giới hạn ở từng địa chỉ riêng lẻ chứ không phải toàn bộ tên miền này, trong khi cả hai tên áp dụng cho mọi địa chỉ trên tên miền. Khóa có tên miền nằm trong domainAllowlist mới được thiết lập chúng. paramdomainAllowlist.