SDK
Liệt kê và truy xuất
`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` và `emails.listEvents`.
emails.list
const first = await openemail.emails.list({ status: ['queued', 'scheduled'], from: '[email protected]', limit: 50,}) const second = first.nextCursor ? await openemail.emails.list({ status: ['queued', 'scheduled'], limit: 50, cursor: first.nextCursor }) : nullMột trang có dạng { items, hasMore, nextCursor }. Hãy truyền lại nextCursor làm cursor, cùng các bộ lọc như cũ, để lấy trang kế tiếp.
emails.iterate và emails.listAll
for await (const email of openemail.emails.iterate({ status: 'failed' })) { console.error(email.id, email.lastError)} const failures = await openemail.emails.listAll({ status: 'failed', from: '[email protected]' })Cả hai đều tự đi theo nextCursor cho bạn. iterate chỉ tải một trang khi vòng lặp chạm tới nó, nên thoát vòng lặp sẽ dừng các request, còn listAll duyệt hết mọi trang trước khi phân giải ra một mảng, nên hãy dùng bộ lọc có giới hạn. Cả hai đều dùng phân trang keyset, nên thư đến giữa chừng không thể khiến nó bỏ sót dòng như với offset.
emails.get và emails.listEvents
const email = await openemail.emails.get('msg_…')console.log(email.status, email.recipients) const events = await openemail.emails.listEvents('msg_…')for (const event of events) console.log(event.type, event.createdAt)get là lệnh gọi duy nhất trả về recipients, mỗi địa chỉ một dòng. Một danh sách năm mươi thư, mỗi thư kèm danh sách người nhận, là cả một trang báo cáo không ai yêu cầu.
Tham số
statusEmailStatus | EmailStatus[]- Một hoặc nhiều trạng thái (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), khớp với bất kỳ trạng thái nào trong số đó. SDK gửi mảng dưới dạng một giá trị phân tách bằng dấu phẩy vì máy chủ tách theo dấu phẩy; giá trị ngoài tập này trả về 422 nêu rõ giá trị không hợp lệ.
fromstring- Khớp chính xác với địa chỉ gửi đã ghi nhận, tức `addr@host` trần ở dạng chữ thường. Bản ghi được lưu sau khi bỏ tên hiển thị, nên một angle-addr như `Acme <[email protected]>` không khớp với gì. Giá trị của bạn được chuyển về chữ thường trước khi so sánh, và đây là so sánh bằng chứ không phải khớp tiền tố hay khớp domain.
limitnumber- Số dòng trong trang này, từ 1 đến 100, mặc định 25. Giá trị ngoài khoảng này bị từ chối với 422 chứ không bị ép về giới hạn.
cursorstring- Một message id (`msg_…`) để bắt đầu phân trang. Dùng keyset chứ không dùng offset: các dòng trả về đều cũ hơn hẳn `createdAt` của thư đó, nên thư gửi đến giữa chừng không thể đẩy một dòng vượt qua bạn. Một id không trỏ tới thư nào trong workspace này trả về 400.
Phản hồi: Page<EmailResource>
itemsEmailResource[]- Một trang thư, mới nhất trước theo `createdAt`, đã được tách khỏi phong bì `data` của API. Các dòng danh sách không bao giờ có phần chi tiết `recipients` theo từng địa chỉ. Phần đó có trên `get`.
hasMoreboolean- Còn dòng nào khớp bộ lọc ngoài trang này hay không. Được xác định bằng cách lấy thêm một dòng so với `limit` chứ không phải bằng một truy vấn đếm riêng.
nextCursorstring | null- Id để truyền lại làm `cursor`, và null ở trang cuối. `iterate` và `listAll` dừng khi trường này là null hoặc `hasMore` là false, vì một trang báo còn dữ liệu mà không có cursor sẽ lặp vô tận.
items[].object'email'- Luôn là `'email'` trên mỗi dòng của danh sách này.
items[].idstring- Id riêng của API này, `msg_…`. Đây là id mà mọi endpoint emails khác nhận, và là thứ mà cursor trỏ tới.
items[].statusEmailStatus- Giai đoạn hiện tại của thư trong vòng đời. `partial` là một trạng thái riêng chứ không phải một dạng của failed: một số người nhận đã nhận thư và không thể thu hồi, nên thử lại là sai.
items[].modeApiKeyMode- `live` hoặc `test`, lấy theo key đã gửi. Lần gửi ở chế độ test được ghi lại ở đây và không bao giờ thực sự được gửi đi.
items[].fromstring- Địa chỉ mà lần gửi được cấp quyền, lưu ở dạng trần và chữ thường, nên tên hiển thị trong `from` vẫn được gửi đi nhưng không được lưu ở đây. Là chuỗi thuần chứ không phải object vì đây là danh tính đã được cấp quyền: một địa chỉ nằm ngoài phạm vi gửi của key, không thuộc domain mà key nắm giữ và cũng không được khai báo trên key, sẽ bị từ chối với 403, không bao giờ bị âm thầm thay bằng một địa chỉ được phép.
items[].subjectstring | null- Subject đúng như đã lưu. Null với thư được ghi nhận mà không có subject.
items[].messageIdstring | null- Message-ID theo RFC 5322, không phải id của chúng tôi. Null cho tới khi có MIME, và bị dịch vụ gửi thư viết lại khi gửi đi, nên thư báo trả lại hay DSN về sau sẽ mang id khác và cần đối chiếu qua `items[].id`.
items[].threadIdstring | null- Luồng mà thư này thuộc về, nếu được cung cấp hoặc được gán. Ngược lại là null.
items[].transportEmailTransport | (string & {}) | null- Phương thức truyền tải đã dùng để gửi. Null cho tới khi gửi đi, và kiểu để mở để một phương thức truyền tải mà SDK này chưa liệt kê không gây thay đổi phá vỡ: các bản ghi đã lưu vẫn có thể nêu những phương thức không còn dùng nữa.
items[].attemptsnumber- Số lần thư đã được thử gửi, là 0 trước lần đầu tiên.
items[].lastErrorstring | null- Lỗi gửi gần nhất, viết cho người đọc. Null khi chưa có gì thất bại.
items[].scheduledAtstring | null- Thời điểm thư sẽ được gửi, dạng thời điểm ISO-8601. Chỉ null với lần gửi ngay không có cửa sổ hủy: cửa sổ này chỉ là một khoảng trễ ngắn, nên `cancellableForSeconds` cũng điền giá trị cho trường này, trên dòng có `status` là `queued` chứ không phải `scheduled`.
items[].cancellableUntilstring | null- Thời điểm thư sẽ được gửi, cùng giá trị với `scheduledAt` trên mọi lần gửi được hoãn và null với lần gửi không hoãn. Đây là mốc thời gian để hiển thị chứ không phải điều kiện máy chủ kiểm tra: `cancel` dựa vào `status`, và chỉ dừng được thư khi nó còn ở `queued` hoặc `scheduled`.
items[].sentAtstring | null- Thời điểm thư đã được gửi. Null cho tới khi việc gửi hoàn tất, đó là lý do nên rẽ nhánh theo `status` chứ không theo trường này.
items[].tagsRecord<string, string>- Các nhãn được cung cấp khi gửi, trả về nguyên và không bao giờ được diễn giải. Luôn là một object (`{}` khi không có nhãn nào, không bao giờ null), và chỉ được trả về nguyên: endpoint này lọc theo `status` và `from`, nên tag là thứ để đọc trên thư chứ không phải cách để tìm thư.
items[].sourceEmailSource- Nguồn đã yêu cầu gửi: `composer`, `api`, `mcp`, `ai` hoặc `queue`. `api` chính là client này.
items[].createdAtstring- Thời điểm bản ghi gửi được tạo, trước khi gửi đi. Đây là trường mà danh sách dùng để sắp xếp và cursor dùng để so sánh.
items[].trackingEmailTrackingSummary- Bản tóm tắt tương tác, chỉ có trên dòng mà thư được theo dõi, không có trong trường hợp ngược lại. Việc không có trường này chính là câu trả lời cho "thư này có được theo dõi không", trong khi `openCount: 0` sẽ bị hiểu là "không ai mở thư".
items[].tracking.opensboolean- Thư này có được gắn pixel theo dõi hay không. Đây là thứ đã áp dụng cho thư này, không phải giá trị cài đặt tài khoản hiện tại.
items[].tracking.clicksboolean- Các liên kết trong thư này có được viết lại hay không. False khi phần thân không có liên kết nào để viết lại, vì khi đó không có gì bị thay đổi.
items[].tracking.openedboolean- Đã ghi nhận lượt mở hợp lệ nào hay chưa, suy ra từ `openCount > 0`.
items[].tracking.clickedboolean- Đã ghi nhận lượt nhấp hợp lệ nào hay chưa, suy ra từ `clickCount > 0`.
items[].tracking.openCountnumber- Số lượt mở được cho là do người thật thực hiện, cộng dồn trên mọi bản sao của thư. Trình quét và proxy bảo vệ quyền riêng tư vẫn được ghi nhận nhưng bị loại trừ, và các lần tải lặp lại trong vòng ba mươi giây được gộp thành một.
items[].tracking.clickCountnumber- Số lượt nhấp hợp lệ, cộng dồn trên các bản sao. Khử trùng lặp theo từng liên kết chứ không theo từng thư, vì nhấp hai liên kết cách nhau vài giây là hai hành động chứ không phải lặp lại.
items[].tracking.firstOpenAtstring | null- Lượt mở hợp lệ sớm nhất trên các bản sao, và null khi chưa có. Lượt truy cập của máy không bao giờ thay đổi giá trị này.
items[].translationEmailTranslationResource- Không bao giờ có trên dòng danh sách: bản ghi dịch nằm trong request đã lưu, thứ mà thao tác liệt kê cố ý không tải. Việc không có trường này ở đây không cho biết thư có được dịch hay không. Hãy dùng `get`.