# 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.

```ts
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](/docs/sdks/typescript/errors#retries-and-idempotent-sends). |
| `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](/docs/sdks/typescript/live-events) 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`](/docs/sdks/typescript/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](/docs/guides/authentication) 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`](/docs/sdks/typescript/branding/get) or
  [`system.health`](/docs/sdks/typescript/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](/docs/sdks/typescript/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](/docs/sdks/typescript/calling-methods#call-options)),
  `RetryOptions` ([the retry policy](/docs/sdks/typescript/errors#the-retry-policy)), `WebSocketConstructor` and `SocketInit`
  (what a `WebSocket` given to it must be), and every type of the API
  ([Types](/docs/sdks/typescript/types)).
