SDK
Hẹn giờ và hủy
`scheduledAt`, `emails.reschedule` và `emails.cancel`.
Gửi sau
await openemail.emails.send({ ...message, scheduledAt: 'PT1H' })await openemail.emails.send({ ...message, scheduledAt: new Date('2027-01-01T09:00:00Z') })await openemail.emails.send({ ...message, scheduledAt: '2027-01-01T09:00:00.000Z' })Một Date, một thời điểm ISO-8601, hoặc một khoảng thời gian như PT1H / P2D. Tối đa một năm tới, không bao giờ ở quá khứ.
Dời lịch và dừng gửi
const queued = await openemail.emails.send({ ...message, scheduledAt: 'PT1H' }) await openemail.emails.reschedule(queued.id, new Date(Date.now() + 86_400_000))await openemail.emails.cancel(queued.id)Chỉ thư queued và scheduled mới có thể dừng; mọi trạng thái sau đó đều là conflict_error, vì một phần đã nằm trong hộp thư của ai đó. Hủy một thư đã bị hủy vẫn thành công và không thay đổi gì.
Dùng cửa sổ hoàn tác thay thế
await openemail.emails.send({ ...message, cancellableForSeconds: 30 })Thư đã hẹn giờ vốn có thể hủy cho tới khi được gửi, nên không thể kết hợp hai cơ chế, và máy chủ sẽ từ chối. Hãy dùng cơ chế này làm cửa sổ hoàn tác cho thư gửi ngay.
Tham số: hẹn giờ
scheduledAtDate | string- Thời điểm gửi, trên `emails.send`: một `Date`, một thời điểm ISO-8601, hoặc một khoảng thời gian như `PT1H` hay `P2D`, được client chuyển thành chuỗi khi truyền đi. Ít nhất một giây trong tương lai và tối đa 365 ngày tới, vi phạm bất kỳ giới hạn nào đều là `validation_error` trên `scheduledAt`, và ngôn ngữ tự nhiên không được chấp nhận, vì hiểu sai "thứ Ba tới" sẽ gửi thư vào một thời điểm không thể rút lại.
cancellableForSecondsnumber- Cửa sổ hoàn tác cho lần gửi NGAY: một integer từ 0 đến 900, mặc định 0. Mọi giá trị lớn hơn 0 đều bị từ chối nếu đi cùng `scheduledAt`, vốn đã có thể hủy cho tới khi được gửi, và thư được giữ theo cách này ở trạng thái `queued` chứ không phải `scheduled`. Đây là cùng một cơ chế hoãn với khoảng trễ ngắn.
idstringbắt buộc- Id `msg_…`, là đối số đầu tiên của cả `emails.cancel` và `emails.reschedule`. Cả hai đều cần `emails:send` chứ không có scope riêng, và đều phân giải trong workspace của key, nên id thuộc workspace khác trả về `not_found_error` y như id chưa từng tồn tại.
reschedule.scheduledAtDate | stringbắt buộc- Thời điểm mới, là đối số thứ hai của `emails.reschedule`, được phân tích theo cùng quy tắc và cùng giới hạn một năm, và là thứ duy nhất mà `PATCH /emails/{id}` bên dưới thay đổi. Khoảng thời gian được tính tương đối theo lúc MÁY CHỦ đọc nó, nên lần dời lịch được thử lại sẽ rơi muộn hơn lần đầu một chút: chỉ muộn hơn, không bao giờ sớm hơn.
Phản hồi: EmailResource
object'email'- Luôn là `email`. Cả hai lệnh gọi đều trả về toàn bộ thư chứ không chỉ xác nhận, nên không cần tải lại để xem điều gì đã thay đổi; `emails.send` trả về đúng cấu trúc này cộng thêm `replayed`.
idstring- Định danh `msg_…`. Ổn định suốt vòng đời của thư và là id mà mọi lệnh gọi khác trên thư này nhận.
statusEmailStatus- `cancelled` sau khi hủy và `scheduled` sau khi dời lịch, kể cả với thư chỉ đang `queued` sau cửa sổ hoàn tác, thứ mà việc dời lịch biến thành một lịch gửi thật. Chỉ thư `queued` và `scheduled` mới có thể dời lịch hoặc dừng; mọi trạng thái sau đó đều là `conflict_error` với mã `email_not_cancellable`, vì một phần đã nằm trong hộp thư của ai đó.
scheduledAtstring | null- Thời điểm ISO mà thư sẽ được gửi đi. Được đặt cho cả cửa sổ hoàn tác lẫn lần gửi có `scheduledAt`, vì hai thứ này là cùng một cơ chế, và null với lần gửi ngay thông thường.
cancellableUntilstring | null- Thời điểm không còn hủy được nữa, trùng với `scheduledAt` trên cả hai cách hoãn. Null với lần gửi ngay, vốn đã được gửi đi khi lệnh gọi trả về.
sentAtstring | null- Thời điểm thư thực sự được gửi đi. Null khi còn đang chờ, và luôn null với thư đã hủy.
messageIdstring | null- Message-ID theo RFC 5322, null cho tới khi có MIME, nên luôn null trên thư mà hai lệnh gọi này có thể tác động. Không dùng để gọi API, và cũng không phải thứ mà thư báo trả lại về sau mang theo: dịch vụ gửi thư viết lại header này khi gửi đi.
threadIdstring | null- Luồng mà thư này thuộc về, lấy từ request và được ghi đè bằng giá trị mà tầng truyền tải báo về khi gửi. Null khi không phải thư trả lời.
transportEmailTransport | (string & {}) | null- Phương thức truyền tải đã dùng để gửi, null cho tới khi gửi đi, nên null trên mọi thư mà lệnh hủy hoặc dời lịch có thể trả về. Lần gửi ở chế độ test ghi `test`, và union để 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ỡ.
attemptsnumber- Số lần tiến trình gửi đã nhận xử lý dòng này. Giá trị tăng khi dòng được nhận xử lý chứ không phải khi gửi thành công, và là 0 với thư còn đang chờ.
lastErrorstring | null- Lỗi gần nhất ghi nhận cho thư, null khi chưa có gì thất bại. Một lần gửi được hoãn mà job của nó không thể đưa vào hàng đợi sẽ được ghi ở đây dạng `Could not schedule: …` và chuyển sang `failed`, đó là cách duy nhất một thư đã hẹn giờ không còn hủy được mà không ai yêu cầu.
fromstring- Địa chỉ mà thư được cấp quyền dùng để gửi, lưu ở dạng trần và chữ thường. Không phải lúc nào cũng là địa chỉ được yêu cầu (một key bị giới hạn mà không nêu `from` sẽ phân giải ra địa chỉ đầu tiên nó được phép dùng), và mọi tên hiển thị đều bị bỏ ở đây, vì bộ lọc `from` của `emails.list` so sánh bằng.