Skip to Content

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

OptionDefaultWhat it does
apiKeyOPENEMAIL_API_KEYAn 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.
baseUrlOPENEMAIL_BASE_URL, else https://api.open.emailTrailing 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.
timeout60 000 msHow 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.
retrytwo retries, Retry-After up to 3 sWhich calls are sent again, and how often: see Errors and retries.
headersnoneSent with every request. A live channel's upgrade carries only its call's own headers, and the credential.
fetchthe runtime'sThe fetch every request is sent with, for a proxy or a test.
userAgentopenemail-sdk-ts/1.2.0Not sent from a browser, which forbids it, nor with a live channel's upgrade.
WebSocketthe runtime'sWhat the live channels open their sockets with: a WebSocketConstructor, new (url, { headers }).
dangerouslyAllowBrowserfalseA 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.get or system.health.
  • No call follows a redirect. The API never answers one, so a redirect is a baseUrl gone wrong: the call fails (a RequestError of kind network) 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 WebSocket that 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, PagePromise and RealtimeConnection are 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

  • OpenEmail is also its default export: import OpenEmail from '@openemail/sdk'.
  • DEFAULT_BASE_URL is the address a client calls when it is given none, and SDK_VERSION the package's version, what its User-Agent says.
  • Its types: ClientOptions (the options above), CallOptions (every call's own), RetryOptions (the retry policy), WebSocketConstructor and SocketInit (what a WebSocket given to it must be), and every type of the API (Types).