The client
The TypeScript SDK's client: its credential, the API's address, timeouts and retries, headers, its fetch and WebSocket, and why a browser is refused.
One client holds the credential and every setting; its namespaces
(openemail.domains, openemail.messages...) are the API's methods.
import { OpenEmail } from '@openemail/sdk'
const openemail = new OpenEmail({
apiKey: 'oek_…', // or an oemp_ mailbox app password; default OPENEMAIL_API_KEY
baseUrl: 'https://api.open.email', // default OPENEMAIL_BASE_URL, else this
timeout: 60_000, // per send, body included; 0 for none
retry: { attempts: 2 }, // false, a number, or RetryOptions
headers: { 'X-Team': 'mail' }, // sent with every request
})Options
| Option | Default | What it does |
|---|---|---|
apiKey | OPENEMAIL_API_KEY | An account API key (oek_…: the account, or only the domains it is limited to) or a mailbox app password (oemp_…, one mailbox). Without one only the public operations work (a domain's branding, the health check, the token links); any other rejects with a TypeError (a live channel's throws it) and sends nothing. |
baseUrl | OPENEMAIL_BASE_URL, else https://api.open.email | Trailing slashes dropped, a path prefix kept. Plain http is refused with a credential, but to this machine (localhost, 127.x.x.x, ::1), for a local API. |
timeout | 60 000 ms | How long one send waits for its answer, body included. Longer than 30 s on purpose: the API gives a domain's creation and its DNS check up to 30 s of its own, and a client must outwait the server. |
retry | two retries, Retry-After up to 3 s | Which calls are sent again, and how often: see Errors and retries. |
headers | none | Sent with every request. A live channel's upgrade carries only its call's own headers, and the credential. |
fetch | the runtime's | The fetch every request is sent with, for a proxy or a test. |
userAgent | openemail-sdk-ts/1.2.0 | Not sent from a browser, which forbids it, nor with a live channel's upgrade. |
WebSocket | the runtime's | What the live channels open their sockets with: a WebSocketConstructor, new (url, { headers }). |
dangerouslyAllowBrowser | false | A credential in a browser is refused unless this is true (below). |
The credential
An account API key reaches the account and every mailbox under it, or, when it
is limited to some domains, only those domains and their mailboxes: an
account-level call then answers 403 account_credentials_required. A mailbox
app password reaches exactly that one mailbox.
auth.whoami says which one the client
holds and what it reaches: for an app password, its mailbox's id
(mailboxId), the one its methods take; for a key limited to some domains,
those domains. The
Authentication guide has the scope rules.
The client sends the key as it is and never decides its reach: the API does.
A limited key works through the SDK exactly as it does over HTTP. A call on
its domains, or on a mailbox with an address on them, goes through; an
account-level call rejects with a RequestError whose code is
account_credentials_required (403), and another domain's resource with
not_found (404).
- The credential goes only where it belongs: to the API's address, and
never with an operation the API declares public, such as
branding.getorsystem.health. - No call follows a redirect. The API never answers one, so a redirect
is a
baseUrlgone wrong: the call fails (aRequestErrorof kindnetwork) instead of carrying the request where nobody meant it to go. - A client without one can still call those, and nothing else: any other method rejects before it sends (a live channel's throws).
In a browser
The client refuses to run in a browser with a credential: anyone who can load the page can read the key, and with an account key do anything to the account. Keep the key on a server and call your server from the page.
dangerouslyAllowBrowser: true lifts the refusal for a credential that is
the user's own, such as an app password they typed into your page: the user
can read only what they gave.
Where it runs
On the web platform's globals alone (fetch, Blob, WebSocket, Web
Crypto): Node 22.12 and later, Bun, Deno (as npm:@openemail/sdk), Cloudflare
Workers, and a browser with dangerouslyAllowBrowser. The package has no
dependencies.
- Live events need a
WebSocketthat sends headers: Node 22.12 and later and Bun have one. Elsewhere, give the client one that does, or use webhooks. - It is an ES module, which CommonJS loads with
require()too. - Its types need TypeScript 5.0 or later: from CommonJS, 5.8 or later
with
module: nodenext. - What a method answers is a type to name, never a class to construct:
ApiPromise,PagePromiseandRealtimeConnectionare exported as types only.
A new operation in the API
Every operation of the API is a method. A new one becomes a method in the next release of the SDK: update the package to call it.
What else the package holds
OpenEmailis also its default export:import OpenEmail from '@openemail/sdk'.DEFAULT_BASE_URLis the address a client calls when it is given none, andSDK_VERSIONthe package's version, what its User-Agent says.- Its types:
ClientOptions(the options above),CallOptions(every call's own),RetryOptions(the retry policy),WebSocketConstructorandSocketInit(what aWebSocketgiven to it must be), and every type of the API (Types).
TypeScript SDK
The OpenEmail API from TypeScript with @openemail/sdk: every operation a typed method, with listings, one error type, webhook checks and live events.
Calling methods
How a TypeScript SDK method takes its arguments: the path's parameters, the body or its raw bytes, the operation's options, and what every call takes.