SDK

구성

클라이언트를 만드는 세 가지 방법, 모든 옵션, 그리고 요청을 보내기 전에 거부하는 것들.

옵션

openemail.ts

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_…')

진입점	제공하는 것
`init(options)`	공유 클라이언트를 구성하고 반환합니다. 그때부터 모든 모듈에서 `openemail`이 그 클라이언트이며, 생략한 값은 환경 변수에서 읽습니다.
`openemail`	공유 클라이언트입니다. `init` 전에 사용하면 첫 호출 시 `OPENEMAIL_API_KEY`와 `OPENEMAIL_BASE_URL`로 스스로를 구성합니다.
`createOpenEmail(options)`	같은 환경 변수 폴백을 쓰는 별도의 클라이언트입니다. 공유 클라이언트와 별개로 두 번째 키를 쓰거나, 직접 만든 모듈이 export할 인스턴스를 구성할 때 씁니다. `createClient`는 envless SDK가 쓰는 이름으로 노출된 동일한 함수입니다.
`new OpenEmail(options)` 또는 `new OpenEmail(apiKey)`	전달한 값만으로 구성되는 별도의 클라이언트입니다. 환경 변수를 읽지 않으므로 `apiKey`가 필수입니다. 기본 export이기도 합니다.

options.ts

init({  apiKey: 'oe_live_…',  baseUrl: 'https://api.openemail.uk',  timeoutMs: 30_000,  maxRetries: 2,  fetch: myFetch,  headers: {},  userAgent: 'billing-service/1.4',  disableUpdateNotice: true,})

옵션	기본값	비고
`apiKey`	`OPENEMAIL_API_KEY`	`init`과 `createOpenEmail`이 환경 변수에서 읽습니다. `oe_live_` 또는 `oe_test_`로 시작해야 합니다.
`baseUrl`	`https://api.openemail.uk`	또는 `OPENEMAIL_BASE_URL`. 끝의 슬래시는 제거되며, `init`과 `createOpenEmail`은 호스트만 적힌 값 앞에 `https://`를, localhost 앞에는 `http://`를 붙입니다.
`timeoutMs`	30000	호출 단위가 아니라 시도 단위입니다. 헤더뿐 아니라 본문을 읽는 시간까지 포함합니다. 0이면 비활성화됩니다.
`maxRetries`	2	반복해도 안전한 호출에 한해, 첫 시도 이후의 추가 시도 횟수입니다. 호출별이 아니라 클라이언트에 설정합니다.
`fetch`	전역 fetch	바인딩은 알아서 처리됩니다. 프록시, Worker 바인딩, 테스트 더블을 쓰려면 직접 전달하세요.
`headers`	`{}`	모든 요청에 전송됩니다.
`userAgent`	`openemail-sdk/<version>`	설정을 허용하지 않는 브라우저를 제외한 모든 런타임에서 전송됩니다.
`disableUpdateNotice`	false	npm에 새 버전이 있는지 프로세스당 한 번 확인하는 절차를 건너뜁니다. 이 확인은 출력이 터미널로 갈 때만 실행되며, `OPENEMAIL_DISABLE_UPDATE_NOTICE`로도 끌 수 있습니다.
`dangerouslyAllowBrowser`	false	`window`와 `document`가 존재하는 환경에서도 클라이언트를 시작하게 합니다. 페이지가 아니라 그것들을 정의하는 테스트 하네스를 위한 옵션입니다.

보내기 전에 거부하는 것

이들은 잘못된 값이 들어간 바로 그 줄에서 평범한 Error를 던지며, 첫 발송에서 알 수 없는 실패로 나타나지 않습니다. 메시지가 무엇이 잘못되었고 대신 무엇을 넘겨야 하는지 알려 줍니다.

거부되는 것	이유
키가 전혀 없음	`apiKey`도 `OPENEMAIL_API_KEY`도 설정되지 않아 인증할 수단이 없습니다.
세션 쿠키 또는 세션 토큰	여기서 인증되는 것은 `oe_live_`와 `oe_test_`뿐이며, API도 같은 말을 합니다. 검사는 접두사 확인 그 이상이 아니므로, 폐기된 키는 여전히 통신 단계에서 실패합니다.
http 또는 https URL이 아닌 `baseUrl`	그 외의 것은 fetch할 수 없으며, 검증하지 않으면 나중에 전혀 다른 곳에서 날것의 `TypeError`로 실패합니다.
브라우저	devtools를 여는 누구나 키를 읽을 수 있게 됩니다. 아래 절을 참고하세요.
`fetch`가 어디에도 없음	`fetch`로 하나를 전달하거나 Node 20+에서 실행하세요.
메서드에 빈 id나 점으로만 이루어진 id를 전달	메서드를 호출할 때 던져집니다. 점으로 이루어진 경로 세그먼트는 모든 URL 파서가 제거하므로, 요청이 다른 엔드포인트에 도달하게 됩니다.

testMode 옵션은 없고 앞으로도 없을 것입니다. 키 체계는 힌트가 아니라 자격 증명의 일부이므로, 모드는 키의 속성입니다. openemail.mode는 접두사를 읽을 뿐 아무것도 결정하지 않습니다.

하나의 클라이언트, 여러 개의 키

클라이언트는 한 번 만들어 공유하세요. 요청마다 새 인스턴스를 만들면 fetch 바인딩과 설정을 헛되이 버리는 셈이고, 인스턴스에 담긴 상태 중 호출자별로 달라지는 것은 없습니다.

여러 워크스페이스를 대신해 발송하는 작업처럼 키마다 인스턴스를 만들어야 할 상황에서는 호출에 apiKey를 전달하세요. 그 요청에 한해 Authorization 헤더를 대체하며 클라이언트에는 아무것도 남기지 않습니다.

per-call-key.ts

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 })

tempMail 밖의 모든 메서드가 마지막 인자에서 signal과 나란히 이 값을 받으며, 목록 호출에서는 필터와 같은 객체에 담깁니다. 이 값은 생성자와 같은 규칙으로 요청 전에 검사되므로, 오타가 나면 나중에 찾아 헤매야 할 자격 증명에 대한 401이 아니라 { apiKey } on this call을 지목하는 Error가 던져집니다. 재시도된 호출은 받은 키를 그대로 유지합니다.

signal은 AbortSignal입니다. 중단하면 요청과, 그 뒤에서 대기 중인 재시도까지 멈춥니다.

openemail.mode는 클라이언트를 생성할 때 사용한 키를 설명하며, 호출별 재정의를 따라가지 않습니다. 하나의 클라이언트가 여러 키를 쓰는 순간 보고할 단일 모드가 없어지므로, 전달한 키에서 직접 읽으세요.

브라우저에서

클라이언트는 브라우저에서 시작하기를 거부하고 요청이 나가기 전에 예외를 던집니다. 페이지에 넣은 키는 이미 공개한 키입니다. devtools를 여는 누구나 그 키로 메일을 보내고 메일함을 읽을 수 있습니다. 대신 서버나 서버리스 함수, 스크립트에서 호출하세요.

일회용 받은편지함은 예외입니다. createTempMail()은 API 키를 담지 않는 클라이언트를 만들므로 페이지에서 안전합니다. 익명으로 받은편지함을 만들고, 읽을 때마다 create가 반환한 토큰을 호출별 inboxToken으로 보내거나 createTempMail({ inboxToken })으로 한 번에 지정합니다.

temp-mail.ts

import { createTempMail } from '@openemail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })

그래도 dangerouslyAllowBrowser: true를 전달하는 경우, API는 CORS 프리플라이트에서 Content-Type, Authorization, Idempotency-Key만 허용하므로 headers에 헤더를 추가하면 요청이 아니라 프리플라이트가 실패하고, 그에 대해 브라우저가 보고하는 내용은 쓸모가 없습니다.