Cơ sở kiến thức
REST API
Một API HTTP có tài liệu đầy đủ với các khóa cấp được, giới hạn phạm vi được và thu hồi được.
Chi tiết
- Bật, ở mọi nơi. API phục vụ 104 thao tác có tài liệu trên 68 đường dẫn (email, thread, bản nháp, nhãn, liên hệ, tệp đối tượng, tên miền, mẫu, quy tắc, vai trò, thành viên, cài đặt, lịch, theo dõi, webhook và tài khoản) phía sau một tài liệu OpenAPI 3.1 được cam kết mà bạn có thể đọc không cần khóa tại GET /openapi.json. Quyền truy cập do khóa không gian làm việc bạn cấp trong Cài đặt quyết định.
- Phần bền vững dữ liệu mà tính năng này từng phải chờ nay đã xong. Một lần gửi sẽ ghi một dòng trước khi bất cứ thứ gì được điều phối đi, với một id công khai dạng msg_ theo sau là 24 ký tự hex, và GET /emails/{id} phân giải nó, cùng với /events cho dấu vết theo từng người nhận và /tracking cho lượt mở và lượt bấm. Một Idempotency-Key dài 1–255 ký tự được giữ chỗ dựa trên một chỉ mục duy nhất gồm khóa đó cùng với khóa API của bạn, nên một lần thử lại sau khi hết thời gian chờ sẽ trả về kết quả đầu tiên kèm Idempotency-Replayed: true thay vì gửi hai lần. Một lần gửi có kèm khóa trả về 200 khi đã hoàn tất và 202 khi vẫn còn nằm trong hàng đợi hoặc chờ theo lịch.
- Khóa được tạo, giới hạn phạm vi, xoay vòng và thu hồi trong Cài đặt → Khóa API. Mọi khóa do bảng điều khiển cấp đều là khóa oe_live_. Tiền tố oe_test_ được bộ xác minh và đường gửi thư hiểu, nơi một lần gửi ở chế độ thử nghiệm được ghi nhận và trả lời là đã gửi mà không bao giờ chạm tới một lớp truyền tải nào, nhưng hiện chưa có gì tạo được khóa loại này, và đưa ra tùy chọn đó trước khi lớp truyền tải rỗng nằm phía trên Durable Object sẽ trao cho bạn một khóa thử nghiệm mà lại gửi thư thật. Một khóa mang phạm vi gửi gồm tối đa 25 tên miền trọn vẹn và 50 địa chỉ đơn lẻ, trong đó một tên miền trọn vẹn cũng bao gồm những địa chỉ được thêm vào nó sau này, một hạn dùng tùy chọn từ 1 đến 3650 ngày, và tùy chọn một vai trò. Vai trò là trần chứ không phải một lần cấp quyền thứ hai: GET /ping trả về cả những scope trên khóa lẫn những scope mà vai trò còn để lại cho nó, nên một lỗi 403 cho một scope mà khóa của bạn nêu rõ ràng đều có nguyên nhân nhìn thấy được. Thu hồi là một thao tác cập nhật chứ không phải xóa, nên một lệnh gọi sau đó sẽ được báo revoked_api_key thay vì chỉ đơn giản là xác thực thất bại. Xoay vòng giữ lại mọi thứ của khóa trừ phần bí mật: id, các scope, phạm vi gửi và lịch sử yêu cầu đều tiếp tục, phần bí mật cũ chết ngay khoảnh khắc phần bí mật mới được tạo, và một khóa có keys:write có thể tự xoay vòng chính nó qua API. Cũng chính các hành động liệt kê, xoay vòng, thu hồi và bật đó đều có trên máy chủ MCP cho bất kỳ ai có vai trò được phép quản lý khóa.
- Thứ thực sự còn thiếu: API không có endpoint tải tệp lên của riêng nó. Tệp đính kèm nội tuyến được gửi dưới dạng base64 với tổng dung lượng tối đa 5 MB, còn tệp lớn hơn thì được gửi bằng cách nêu tên một tệp đã có trong không gian làm việc theo id của nó, và tệp đó đi kèm dưới dạng một liên kết tải xuống. Thư bị trả lại được xử lý trong hộp thư chứ không phải trong nhật ký gửi: một báo cáo chuyển thư được phân tích, đối chiếu với thư gốc theo Message-ID, gắn nhãn lên thread và đẩy đi dưới dạng webhook email.bounced, nhưng không có gì ghi ngược lại vào dòng gửi, vốn có trạng thái không hề bao gồm bounced, nên qua GET /emails một thư bị trả lại vẫn hiển thị là đã gửi. Thư gửi từ trình soạn thư của ứng dụng cũng không xuất hiện trong GET /emails, vì trình soạn thư không ghi qua cùng một đường gửi.