API

Gửi email

POST /emails: một thư, gửi ngay hoặc gửi sau.

POSTapi.openemail.uk/emails

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.

Yêu cầu

from là bắt buộc. Khác với trình soạn thư, ở đây không có người gửi dự phòng, vì người gửi dự phòng đó là địa chỉ mặc định của không gian làm việc và nó thay đổi một cách âm thầm khi địa chỉ được thêm hoặc gỡ.

Trường	Bắt buộc	Ghi chú
from	có	Một địa chỉ trơn hoặc `Name <addr>`. Phải là địa chỉ mà khóa được phép dùng để gửi.
to	có	Tối đa 50 người nhận tính gộp cả to, cc và bcc.
cc, bcc	không	Người nhận Bcc không bao giờ xuất hiện trong dữ liệu mà bất kỳ ai khác nhận được.
subject	không	Mặc định là rỗng.
html, text	một trong số	Gửi cả hai cũng được. HTML là phần người nhận nhìn thấy.
template	một trong số	`{ id, version?, props?, slots? }`. Một nội dung đã lưu, theo id hoặc slug. Bị từ chối nếu đi kèm html, text hoặc `draftId`. Xem mục Gửi bằng mẫu.
replyTo	không	Một địa chỉ duy nhất.
headers	không	`X-`, `List-`, Reply-To, Precedence, Auto-Submitted, Importance, Priority, Feedback-Id.
attachments	không	`{ filename, content, contentType }` dưới dạng base64, tổng cộng 5 MB, hoặc `{ fileId }` trỏ tới một tệp đã có trong không gian làm việc. Tối đa 20 tệp.
attachmentDelivery	không	`mime`, `link` hoặc `auto`. `auto` chuyển tệp thành liên kết khi tệp vượt quá 2 MB trên tên miền có tên miền tệp đang hoạt động. Mặc định theo cài đặt của hộp thư.
threadId	không	Trả lời vào một chuỗi thư hiện có.
draftId	không	Gửi một bản nháp hiện có.
scheduledAt	không	Thời điểm ISO hoặc khoảng thời gian. Xem mục Lên lịch.
cancellableForSeconds	không	Khoảng thời gian hoàn tác từ 0 đến 900 giây cho lần gửi ngay. Bị từ chối nếu đi kèm `scheduledAt`, vì thư đã lên lịch vẫn có thể hủy cho tới lúc được gửi. Xem mục Lên lịch.
signature	không	`false` sẽ bỏ chữ ký khỏi thư này. Nếu không, thư mang chữ ký của địa chỉ gửi, tức chữ ký riêng của địa chỉ đó hoặc chữ ký được thiết lập cho Tất cả địa chỉ.
tags	không	Tối đa 10 nhãn do bạn tự đặt. Được trả lại nguyên văn, không bao giờ được diễn giải.
tracking	không	`{ opens?, clicks? }`. Mỗi trường sẽ ghi đè cài đặt cho thư này; bỏ qua một trường thì phần đó dùng cài đặt của địa chỉ gửi, hoặc nếu không có thì dùng cài đặt Tất cả địa chỉ, và nó được bật trừ khi một trong các cài đặt đó đã tắt nó.
translate	không	`{ to, from?, subject?, includeOriginal? }`. Gửi thư bằng ngôn ngữ của người nhận. Được xử lý khi yêu cầu được chấp nhận, bị từ chối nếu đi kèm `draftId`.

Các trường không xác định bị từ chối thay vì bị bỏ qua, nên một tên viết sai sẽ trả về 422 ngay bây giờ thay vì gây bất ngờ về sau. Các header có thể vô hiệu hóa việc xác thực người gửi (From, Sender, Bcc, Message-ID, Return-Path và các header khác) bị từ chối với reserved_header.

Phản hồi

200 khi thư đã được gửi đi, 202 khi thư vẫn còn bước cần xử lý. Bên gọi rẽ nhánh theo mã trạng thái sẽ đúng trong cả hai trường hợp.

200 OK

{  "object": "email",  "id": "msg_c5f21cc6bfec4e848caf905b",  "status": "sent",  "mode": "live",  "from": "[email protected]",  "subject": "Your September invoice",  "messageId": "<2598…@acme.com>",  "transport": "ses",  "sentAt": "2026-08-29T08:19:08.000Z",  "source": "api",  "replayed": false}

id là định danh bền vững mà bạn lưu giữ, và cũng là id mà các sự kiện chuyển phát gắn vào, vì webhook báo thư trả về (bounce) gọi nó là emailId. messageId là Message-ID theo RFC 5322 và là null cho tới khi MIME được tạo. Đừng dùng nó để đối chiếu: dịch vụ gửi thư ghi đè header đó khi thư đi ra, nên giá trị ở đây không xuất hiện trong bất kỳ báo cáo bounce hay báo cáo chuyển phát nào, và việc so khớp theo nó sẽ không bao giờ khớp.

Bằng ngôn ngữ của người nhận

translate viết thư bằng ngôn ngữ của người khác trước khi gửi đi. Phần nội dung, và cả tiêu đề trừ khi bạn tắt tùy chọn đó, được dịch tại thời điểm yêu cầu được CHẤP NHẬN, cùng quy tắc mà template tuân theo và cũng quan trọng vì những lý do tương tự: thư đã lên lịch mang đúng nội dung đã được duyệt chứ không phải bất cứ thứ gì mô hình tạo ra vào thứ Ba, và một bản dịch không tạo được sẽ khiến lần gửi bị từ chối trước khi có bất kỳ hàng nào được tạo. Không có thư nào được gửi bằng ngôn ngữ mà người gửi không chọn.

translate

tostringbắt buộc: Ngôn ngữ cần viết: một mã BCP-47 (`de`), tên tiếng Anh ("German") hoặc tên của ngôn ngữ đó bằng chính ngôn ngữ ấy ("Deutsch"), dài từ 2 đến 60 ký tự. Cả ba dạng đều được chuẩn hóa về mã trong bảng trước khi làm bất cứ điều gì khác, nên chúng là cùng một yêu cầu; điều này quan trọng vì dấu vân tay Idempotency-Key được tính trên yêu cầu đã phân tích cú pháp. Bí danh cũng được phân giải: `zh-TW` trở thành `zh-Hant`. Giá trị không phân giải được sẽ trả về 422 trên `translate.to`.
fromstring: Ngôn ngữ bạn đã dùng để viết, theo bất kỳ dạng nào trong ba dạng trên. Thuần túy là một tối ưu hóa. Nếu bỏ qua, nội dung sẽ được đọc để xác định ngôn ngữ, tốn một lệnh gọi mô hình ngắn. Nên khai báo trên luồng gửi số lượng lớn, và khi nội dung chủ yếu là tên, con số và liên kết: việc nhận diện sẽ bỏ qua thay vì đoán, và ngôn ngữ nguồn không xác định chỉ khiến bạn mất tên ngôn ngữ trong chú thích phía trên bản gốc. Đây không phải trường `from` ở cấp cao nhất, vốn là một địa chỉ.
subjectboolean: Dịch cả dòng tiêu đề. Mặc định là true; false sẽ gửi tiêu đề đúng như bạn đã viết.
includeOriginalboolean: Đặt nội dung gốc bạn đã viết bên dưới bản dịch, sau một đường phân cách và có chú thích bằng ngôn ngữ của người nhận. Mặc định là true, và nên để bật. Đây là thứ duy nhất cho phép người đọc kiểm tra một câu nghe lạ thay vì phải tin vào một mô hình mà cả hai bên đều không thấy được đầu ra.

curl

curl -X POST "$OE/emails" -H "$AUTH" -H "Content-Type: application/json" \  -d '{    "from": "[email protected]",    "to": ["[email protected]"],    "subject": "Your September invoice",    "html": "<p>Invoice attached. Payment is due on the 14th.</p>",    "translate": { "to": "de" }  }'

200 OK

{  "object": "email",  "id": "msg_c5f21cc6bfec4e848caf905b",  "status": "sent",  "from": "[email protected]",  "subject": "Ihre Rechnung für September",  "translation": {    "language": "de",    "languageName": "German",    "detectedSourceLanguage": "en",    "subject": true,    "includeOriginal": true  }}

translation là trường bổ sung và chỉ xuất hiện trên thư đã được dịch: trên phản hồi này và trên GET /emails/{id}, không bao giờ trên một hàng danh sách, vì danh sách không tải yêu cầu đã lưu và việc nó vắng mặt ở đó không nói lên điều gì. Trường này chứa các mã chứ không phải toàn bộ hàng ngôn ngữ: nó là bản ghi về những gì đã làm, còn GET /languages là nơi chứa tên bản ngữ. subject trên phản hồi là tiêu đề đã dịch, nên bảng điều khiển không bao giờ liệt kê một thư dưới một chuỗi mà người nhận chưa từng thấy.

Hoạt động cùng template, và đây là trường hợp hữu ích: đầu ra ĐÃ KẾT XUẤT là thứ được dịch, nên một nội dung đã lưu phục vụ được mọi ngôn ngữ mà khách hàng của bạn đọc. Một mẫu kết xuất ra cả một tài liệu sẽ được tách ra trước: chỉ phần bên trong <body> được gửi tới mô hình, còn doctype, các khối <style> và các quy tắc @font-face được đặt lại bao quanh kết quả. Đó cũng là lý do giới hạn 30.000 ký tự đo phần văn bản chứ không đo cả tài liệu: một thư hai dòng được bọc trong một stylesheet mang thương hiệu vẫn là thư hai dòng.
Phần duy nhất của mẫu không được dịch là <title>, thứ mà không ứng dụng thư nào hiển thị. <Preview> của react-email được kết xuất vào phần thân và được dịch cùng phần còn lại.
Bị từ chối khi đi kèm draftId: lỗi 422 trên translate, với thông báo "A draft is sent as it was written; translate a body or send a draft, not both". Bản nháp do một người viết và được gửi đúng như họ để lại.
Cố ý không nằm trong dấu vân tay idempotency. Thứ được băm là yêu cầu bạn gửi, bao gồm cả translate; thứ mô hình tạo ra thì không. Vì vậy, thử lại một lần gửi chưa nhận được phản hồi với cùng Idempotency-Key sẽ phát lại yêu cầu ban đầu. Thư đã tồn tại được trả về, không có lần gửi thứ hai và không có lần dịch thứ hai. Nếu băm theo câu chữ thay vào đó, một lần thử lại hợp lệ sẽ cho dấu vân tay khác nhau mỗi lần, và đó là cách cùng một thư bị gửi đi hai lần.
Thư đã dịch đang ở hàng đợi hoặc đã lên lịch sẽ bị khóa, không thể thay đổi câu chữ. Bạn có thể dời lịch hoặc hủy; muốn thay đổi nội dung thì phải hủy rồi gửi lại, với một người đọc được câu chữ mới kiểm tra trước.
Ngôn ngữ đích viết từ phải sang trái được tạo theo chiều từ phải sang trái: bản dịch được bọc trong dir="rtl", còn bản gốc của bạn bên dưới giữ hướng riêng của nó. Thuộc tính này được giữ lại qua bộ lọc thư gửi đi, vốn cho phép dir chính vì lý do này, nên thư được truyền đi mang đúng hướng chữ như bản xem trước đã hiển thị.

Mã	Trạng thái	Khi nào
`invalid_parameter`	422	`translate.to` hoặc `translate.from` không chỉ tới ngôn ngữ nào mà chúng tôi xác định được. Thông báo lỗi nêu ba dạng được chấp nhận và chỉ tới `GET /languages`.
`unknown_language`	422	Cùng lỗi đó nhưng bị phát hiện muộn hơn một bước, bởi dịch vụ thay vì schema. Một lớp chặn dự phòng, trên `translate.to`.
`translation_too_long`	422	Vượt quá 30.000 ký tự ở đầu vào hoặc đầu ra của lệnh gọi mô hình. Đây là từ chối chứ không phải cắt bớt: một nửa thư đã dịch không có dấu hiệu nào cho biết nó dừng ở đâu, và người đọc sẽ hành động dựa trên nửa mà họ nhận được.
`translation_not_configured`	409	Không gian làm việc không có khóa AI và AI của nền tảng đang tắt. Trả về 409 thay vì 503 vì thử lại sẽ thất bại y hệt. Không có gì được gửi. Hãy gửi mà không có `translate` nếu bạn muốn gửi đúng như đã viết.
`translation_failed`	503	Nhà cung cấp không phản hồi, hoặc phản hồi không có gì dùng được. Không có gì được gửi; thư không bao giờ được gửi ở dạng chưa dịch như một phương án dự phòng. Lỗi này thuộc về phía chúng tôi và đáng để thử lại.
`unknown_parameter`	422	Một key không được nhận diện bên trong `translate`, vốn là một object nghiêm ngặt như phần còn lại của yêu cầu.

Một lần gửi từ mã nguồn không có ai đọc bản dịch trước. POST /emails/translate là cùng quy trình đó nhưng dừng sớm một bước, để cho một người xem những gì họ sắp gửi. Sau đó hãy gửi nội dung họ đã duyệt dưới dạng html/subject thông thường, hoàn toàn không có translate trong yêu cầu.