Cấu hình
Ba cách tạo client, mọi tùy chọn, và những gì nó từ chối trước khi gửi request.
Tùy chọn
import OpenEmail, { createOpenEmail, init, openemail } from '@openemail/sdk' init({ apiKey: process.env.OPENEMAIL_API_KEY })await openemail.me.ping() export const billing = createOpenEmail({ apiKey: process.env.BILLING_API_KEY! }) const pinned = new OpenEmail({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk' }) const quick = new OpenEmail('oe_live_…')| Điểm vào | Bạn nhận được gì |
|---|---|
| `init(options)` | Cấu hình client dùng chung và trả về nó. Từ đó trở đi openemail chính là client đó, trong mọi module, và bất cứ thứ gì bạn bỏ trống đều được đọc từ biến môi trường. |
| `openemail` | Client dùng chung. Nếu dùng trước init, nó tự khởi tạo từ OPENEMAIL_API_KEY và OPENEMAIL_BASE_URL ở lệnh gọi đầu tiên. |
| `createOpenEmail(options)` | Một client riêng với cùng cơ chế lấy giá trị dự phòng từ môi trường, dùng cho một key thứ hai bên cạnh key dùng chung, hoặc để tạo instance mà module của bạn export. createClient là cùng hàm đó dưới tên mà SDK envless dùng. |
| `new OpenEmail(options)` hoặc `new OpenEmail(apiKey)` | Một client riêng được tạo đúng từ những gì bạn truyền vào. Nó không đọc biến môi trường, nên apiKey là bắt buộc. Đây cũng là default export. |
init({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk', timeoutMs: 30_000, maxRetries: 2, fetch: myFetch, headers: {}, userAgent: 'billing-service/1.4', disableUpdateNotice: true,})| Tùy chọn | Mặc định | Ghi chú |
|---|---|---|
| `apiKey` | OPENEMAIL_API_KEY | Được init và createOpenEmail đọc từ môi trường. Phải bắt đầu bằng oe_live_ hoặc oe_test_. |
| `baseUrl` | https://api.openemail.uk | Hoặc OPENEMAIL_BASE_URL. Dấu gạch chéo cuối bị cắt bỏ, và init cùng createOpenEmail thêm https:// trước một hostname trần, hoặc http:// trước localhost. |
| `timeoutMs` | 30000 | Tính theo mỗi lần thử, không phải mỗi lệnh gọi. Bao gồm cả việc đọc body, không chỉ header. 0 để tắt. |
| `maxRetries` | 2 | Số lần thử thêm sau lần đầu, với các lệnh gọi an toàn khi lặp lại. Đặt trên client, không đặt theo từng lệnh gọi. |
| `fetch` | fetch toàn cục | Được bind sẵn cho bạn. Truyền vào một hàm riêng để dùng proxy, Worker binding hoặc test double. |
| `headers` | {} | Được gửi kèm mọi request. |
| `userAgent` | openemail-sdk/<version> | Được gửi từ mọi runtime trừ trình duyệt, vốn không cho phép đặt header này. |
| `disableUpdateNotice` | false | Bỏ qua lần kiểm tra phiên bản mới trên npm, vốn chạy một lần mỗi tiến trình. Việc kiểm tra chỉ chạy khi đầu ra là terminal, và OPENEMAIL_DISABLE_UPDATE_NOTICE cũng tắt được nó. |
| `dangerouslyAllowBrowser` | false | Cho phép client khởi động ở nơi có window và document. Dành cho môi trường kiểm thử tự định nghĩa chúng, không dành cho trang web. |
Những gì nó từ chối trước khi gửi
Những trường hợp này ném ra một Error thông thường ngay tại dòng có giá trị sai, thay vì biểu hiện thành một lỗi khó hiểu ở lần gửi đầu tiên. Thông báo nói rõ cái gì sai và nên truyền gì thay vào.
| Bị từ chối | Lý do |
|---|---|
| Không có key nào | Cả apiKey lẫn OPENEMAIL_API_KEY đều chưa được đặt, nên không có gì để xác thực. |
| Cookie phiên hoặc token phiên | Chỉ oe_live_ và oe_test_ xác thực được ở đây, và API cũng báo như vậy. Phép kiểm tra chỉ xét tiền tố, nên một key đã bị thu hồi vẫn thất bại khi gửi đi. |
| Một `baseUrl` không phải URL http hay https | Không có gì khác fetch được, và một giá trị chưa được kiểm tra sẽ hỏng về sau dưới dạng một TypeError thô từ một chỗ hoàn toàn khác. |
| Trình duyệt | Key sẽ bị bất kỳ ai mở devtools đọc được. Xem phần bên dưới. |
| Không có `fetch` ở đâu cả | Hãy truyền một hàm vào fetch, hoặc chạy trên Node 20+. |
| Id rỗng hoặc toàn dấu chấm trên bất kỳ phương thức nào | Được ném ra khi phương thức được gọi. Một đoạn path toàn dấu chấm bị mọi bộ phân tích URL loại bỏ, nên request sẽ tới một endpoint khác. |
Không có tùy chọn testMode và sẽ không có. Lược đồ key là một phần của thông tin xác thực chứ không phải gợi ý, nên chế độ là thuộc tính của key. openemail.mode chỉ đọc tiền tố và không quyết định gì.
Một client, nhiều key
Hãy tạo client một lần và dùng chung. Tạo instance mới cho mỗi request là bỏ phí hàm fetch đã bind và cấu hình mà không được gì, và không có trạng thái nào trên nó là riêng cho từng caller.
Với trường hợp lẽ ra buộc phải có một instance cho mỗi key, chẳng hạn một job gửi thay mặt nhiều workspace, hãy truyền apiKey ngay trên lệnh gọi. Nó thay header Authorization cho request đó và không để lại gì trên client.
await openemail.emails.send(message) await openemail.emails.send(message, { apiKey: workspace.apiKey }) await openemail.threads.list({ folder: 'inbox', apiKey: workspace.apiKey })await openemail.webhooks.list({ apiKey: workspace.apiKey })Mọi phương thức ngoài tempMail đều nhận nó ở đối số cuối cùng, bên cạnh signal, và với phương thức list thì đó chính là object chứa bộ lọc. Nó được kiểm tra trước khi gửi request, theo đúng quy tắc mà constructor dùng, nên một lỗi gõ nhầm sẽ ném ra một Error nêu { apiKey } on this call thay vì một 401 về một thông tin xác thực mà bạn phải đi tìm. Một lệnh gọi được thử lại vẫn giữ key đã được truyền.
signal là một AbortSignal. Hủy nó sẽ dừng request, và cả lần thử lại đang chờ phía sau.
openemail.mode mô tả key mà client được TẠO bằng và không phản ánh giá trị ghi đè. Khi một client phục vụ nhiều key thì không còn một chế độ duy nhất để báo cáo, nên hãy xác định nó từ chính key bạn đã truyền.
Từ trình duyệt
Client từ chối khởi động trong trình duyệt và ném lỗi trước khi có bất kỳ request nào. Một key nằm trong trang web là key bạn đã công khai: nó có thể gửi thư và đọc hộp thư cho bất kỳ ai mở devtools. Hãy gọi nó từ máy chủ, hàm serverless hoặc script.
Inbox dùng một lần là ngoại lệ. createTempMail() tạo một client không mang API key nào, nên nó an toàn trong trang web. Nó tạo inbox ẩn danh, và mỗi lần đọc sẽ gửi token mà create đã trả về, hoặc theo từng lệnh gọi qua inboxToken, hoặc một lần qua createTempMail({ inboxToken }).
import { createTempMail } from '@openemail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })Nếu bạn vẫn truyền dangerouslyAllowBrowser: true, API chỉ cho đúng Content-Type, Authorization và Idempotency-Key đi qua CORS preflight, nên một header thừa trong headers sẽ làm hỏng preflight chứ không phải request, và thông báo lỗi của trình duyệt khi đó chẳng cho biết điều gì hữu ích.