Luồng thư

GET /threads?folder=inbox. Truyền query sẽ tìm trên cùng chỉ mục cục bộ đó. Các từ thường phải xuất hiện đủ, và mỗi từ khớp lỏng, bỏ qua hoa thường, dấu và ký tự phân cách, nên min tìm ra "Benjamin". Một cụm trong dấu nháy được khớp đúng như viết, chỉ trừ hoa thường và dấu, nên "ben jamin" không tìm ra "Ben-Jamin". Những từ đệm như the hay emails bị loại khỏi danh sách từ thường khi vẫn còn thứ khác để tìm. Các toán tử như from:, to:, subject:, label:, is:unread, has:pdf, after:2026/01/31 và newer_than:7d thu hẹp kết quả, còn OR, dấu ngoặc đơn và dấu - đứng đầu dùng để kết hợp chúng. Người nhận được lưu thành một danh sách duy nhất không phân vai trò và không bao giờ chứa Bcc, nên cc: đọc cùng trường với to: và bcc: không tự khớp với gì cả. from:me là thư bạn đã gửi, còn to:me là thư có một trong các địa chỉ của chính bạn, kể cả alias, trong danh sách người nhận hoặc làm địa chỉ nhận thư.

Các từ và các toán tử from:, to:, cc:, subject: và body: đọc thư mới nhất trên mỗi luồng: người gửi, người nhận, subject và 4.000 ký tự đầu của phần thân. filename: và has: đọc mọi tệp đính kèm trên toàn bộ cuộc hội thoại, còn label:, in: và is: đọc toàn bộ cuộc hội thoại. folder vẫn áp dụng trừ khi truy vấn nêu một thư mục bằng in:, hoặc bằng một is: là thư mục chẳng hạn is:sent, và in:anywhere tìm trong mọi thư mục, dù đứng một mình hay đi cùng các điều kiện khác. Danh sách bản nháp là ngoại lệ và vẫn giới hạn trong bản nháp bất kể truy vấn nêu gì.

Một giá trị mà tìm kiếm không dùng được sẽ bị bỏ qua thay vì thu hẹp kết quả, nên một lỗi gõ nhầm trong giá trị sẽ làm rộng kết quả chứ không làm nó rỗng: category:, larger:, smaller:, size:, messagesize:, list:, rfc822msgid:, received:, sent:, các từ chỉ danh mục như is:promotions, một từ has: không chỉ loại tệp đính kèm nào, một importance: khác high hoặc low, một ngày không đọc được và một khoảng thời gian có đơn vị không phải h, d, w, m hay y. Một tên toán tử không được nhận ra, chẳng hạn project:, được tìm như văn bản thường. Ngày tháng so với hoạt động mới nhất trên luồng, theo UTC, trong đó after: bao gồm chính ngày được nêu còn before: thì loại trừ; hãy viết ngày dạng YYYY/MM/DD, YYYY-MM-DD, YYYYMMDD, chỉ năm, hoặc epoch tính bằng giây hay mili giây.

GET /threads/{id} trả về mọi thư trong luồng, không chỉ thư mới nhất, kèm nhãn của luồng và cho biết trong đó có thư nào chưa đọc hay không.

API này không mã hóa cũng không giải mã. Nó không thể mở một thư do người khác mã hóa, và không thể gửi một thư đã mã hóa. Một request mang dấu hiệu mã hóa bị từ chối với 422, vì chỉ những nơi giữ khóa mới được đặt dấu hiệu đó, và không API client nào giữ khóa. Việc nó làm là NHẬN RA một phong bì niêm phong khi thư đi vào, chỉ dựa trên Content-Type ở cấp cao nhất và không gì khác, rồi ghi nhận điều đó trên thư.

Bản thân OpenEmail nay đã giữ khóa, và cần nói chính xác là nửa nào và ở đâu. Chủ hộp thư tạo một danh tính OpenPGP trong trình duyệt của họ và công bố khóa CÔNG KHAI lên một danh bạ mà những người gửi OpenEmail đã đăng nhập khác có thể tra cứu. Nửa riêng tư được tạo trong trình duyệt đó, không bao giờ được gửi tới đây và không bao giờ khôi phục được, nên không thứ gì trong API này giải mã được bất cứ gì, và không yêu cầu hỗ trợ, trát tòa hay bản sao lưu nào của chúng tôi tạo ra được một khóa có thể làm việc đó. Ứng dụng web nay có thể MỞ một thư PGP/MIME hoặc inline-PGP khi khóa nằm trong trình duyệt của người đọc, nhưng việc giải mã diễn ra trong tab và bản rõ không bao giờ được ghi ngược lại: thư đã lưu vẫn là bản mã, và không phản hồi nào từ API này mang theo nội dung đã mở. Ứng dụng nay có thể niêm phong một thư mới trong trình duyệt và gửi nó: trình soạn thư mã hóa bằng các khóa công khai đã công bố của người nhận và thư đi ra dưới dạng PGP/MIME. API này vẫn không thể niêm phong gì, nên trường dưới đây mô tả cả thư do người khác mã hóa lẫn thư được niêm phong trong một tab OpenEmail.

Điều đó đáng có một trường riêng vì phương án thay thế là gì. Một thư đã niêm phong không lưu phần thân đọc được, nên decodedBody trả về "", giống hệt một thư thực sự không có nội dung. encryption là thứ giúp bạn phân biệt hai trường hợp trước khi xử lý, và nó là một nhận định về phong bì chứ không phải một lần xác minh: thấy thư đã niêm phong không có nghĩa là đã mở được nó.

{    "object": "thread",    "id": "thread_2f9b…",    "messages": [      {        "id": "msg_7c41…",        "subject": "Q3 numbers",        "decodedBody": "",        "encryption": {          "format": "pgp-mime",          "detectedAt": "2026-08-30T09:14:22.117Z",          "rawRetained": false,          "parts": [            { "index": 0, "attachmentId": "msg_7c41…-0", "role": "version" },            { "index": 1, "attachmentId": "msg_7c41…-1", "role": "ciphertext" }          ]        }      }    ]  }

Chỉ ba định dạng niêm phong mới làm thay đổi điều gì đó, và thay đổi xảy ra lúc nạp thư chứ không phải trong phản hồi này. Mọi thứ lẽ ra sẽ đọc phần thân đều đứng ngoài, thay vì đọc bản mã rồi báo một kết quả mà nó không thể có được:

• —Tìm kiếm trong phần thân. Thư được đánh chỉ mục với đoạn trích phần thân rỗng, nên vẫn tìm được theo người gửi, subject, địa chỉ và nhãn, nhưng không theo bất cứ thứ gì bên trong.
• —Lượt quét phần thân của bộ chấm điểm lừa đảo. Kết luận vẫn có và nêu rõ điều nó không làm được: risk.signals chứa body-encrypted và risk.aiChecked là false.
• —Bước kiểm tra thư do AI viết, vốn từ chối thay vì đoán: aiWritten.level là unknown và aiWritten.skipped là encrypted.
• —Các điều kiện về phần thân trong quy tắc. Điều kiện về phong bì và header vẫn chạy như trước; một quy tắc hỏi về phần thân được ghi nhận là chưa đánh giá chứ không tính là không khớp, vì "không khớp" và "không đọc được" là hai câu trả lời khác nhau.
• —Nhập lời mời lịch. Lời mời nằm bên trong bản mã, và dựng một sự kiện từ phong bì sẽ đặt một mục sai lên một lịch thật.
• —Tóm tắt luồng và embedding, cho toàn bộ luồng. Chỉ cần một thư trả lời niêm phong là đủ. Bản tóm tắt là cách mô hình đọc bản rõ rồi lưu lại dưới dạng metadata không mã hóa, và đó là chỗ duy nhất trong quy trình này mà phần thân có thể rò rỉ vào một kho mà không ai nghĩ là nơi chứa phần thân.

Mọi thứ không cần tới phần thân đều không bị ảnh hưởng:

• —DMARC, DKIM và SPF. Chúng được đọc từ Authentication-Results, thứ mà bản mã không che giấu, nên một thư đã mã hóa vẫn nhận được kết luận xác thực thật thay vì không có gì.
• —Gom luồng, lọc thư rác và danh sách chặn: tất cả đều làm việc trên phong bì và header.
• —Tệp đính kèm. Phần ciphertext vẫn nằm trong attachments, được đặt tên encrypted-message.asc khi nó đến mà không có tên, và tải xuống qua endpoint bên dưới. Đó chính là thứ mà trình đọc của ứng dụng web tải về rồi giải mã trong trình duyệt; với một API client, vốn không giữ khóa nào, lượt tải đó vẫn là cách duy nhất để đọc thư. Hãy mở nó trong một client có khóa.
• —Một thư đã ký không mất gì trong số này. Mọi bước kiểm tra ở trên vẫn chạy trên nó và không có gì bị giữ lại, đó là lý do danh sách niêm phong gồm ba định dạng chứ không phải năm.

PATCH /threads/{id} nhận read, addLabelIds và removeLabelIds. Trạng thái đã đọc là một nhãn trên mọi backend mà sản phẩm này hỗ trợ, nên đặt read và chuyển nhãn trong cùng một lệnh gọi giữ cho thứ tự xử lý xác định.

{ "read": true, "addLabelIds": ["USER_INVOICES"] }

GET /threads/{id}/messages/{messageId}/attachments trả về từng tệp đính kèm với filename, contentType, size và content dạng base64. content là chuỗi rỗng khi không tìm thấy byte đã lưu, nên hãy kiểm tra độ dài của nó trước khi giải mã.