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

`@openemail/sdk` is the API as typed methods. Every operation in the
[API reference](/docs/api/overview) is a method of one client, its arguments
and its answer typed from the same OpenAPI document the reference is drawn
from: all 318 of them, in 46 namespaces. It has no dependencies, and runs on
Node 22.12 or later, Bun, Deno and Cloudflare Workers;
[live events](/docs/sdks/typescript/live-events) need Node 22.12 or later or Bun.

## Install

```bash
npm install @openemail/sdk
```

Its first release is 1.0.0.

## Make a first call

```ts
import { OpenEmail } from '@openemail/sdk'

const openemail = new OpenEmail({ apiKey: process.env.OPENEMAIL_API_KEY })

const me = await openemail.auth.whoami()
```

The key is an account API key (`oek_…`: the account, or only the domains it is
limited to) or a mailbox app password (`oemp_…`, one mailbox). Leave `apiKey` out and the client reads
`OPENEMAIL_API_KEY`. [`auth.whoami`](/docs/sdks/typescript/auth/whoami), the
API's [whoami](/docs/api/credentials/get_AuthWhoami), says what the key
reaches. Keep the key on a server: [The client](/docs/sdks/typescript/client)
says why, and what else the client takes.

## How a method reads

A method reads the way its operation's URL does: the path's parameters in the
order the path names them, then the body when it takes one, then one object of
options.

```ts
const sent = await openemail.messages.send(mailboxId, {
  from: { email: 'ada@example.com', name: 'Ada' },
  to: [{ email: 'grace@example.org' }],
  subject: 'Hello',
  text: 'Hello from the SDK',
})

for await (const message of openemail.messages.list(mailboxId, { label: 'INBOX' })) {
  console.log(message.subject)
}
```

[`messages.send`](/docs/sdks/typescript/messages/send) is the API's
[send](/docs/api/delivery/post_MessageSend), and
[`messages.list`](/docs/sdks/typescript/messages/list) its
[message listing](/docs/api/messages/get_MessageList), every page of it.
(`console.log` stands for your own code.)

## The guides

- [The client](/docs/sdks/typescript/client): the credential, the API's
  address, timeouts, retries, and why a browser is refused.
- [Calling methods](/docs/sdks/typescript/calling-methods): arguments, raw
  bodies, options, and what every call takes.
- [Listings](/docs/sdks/typescript/listings): one page awaited, every item
  iterated.
- [Responses and headers](/docs/sdks/typescript/responses): what a method
  answers, `withResponse()`, ETags and conditional calls.
- [Errors and retries](/docs/sdks/typescript/errors): one error type, its
  codes, and which calls are sent twice.
- [Receiving webhooks](/docs/sdks/typescript/webhooks): registering a hook, verifying and
  parsing what it sends, answering it, and catching up after a failure.
- [Live events](/docs/sdks/typescript/live-events): a mailbox's changes over a
  channel that holds itself open.

## The reference

- [All methods](/docs/sdks/typescript/methods): every namespace, each method
  with what it does and the operation it calls.
- [Error codes](/docs/sdks/typescript/error-codes): every code the API
  documents, with its statuses and the methods that can answer it.
- A page per method: its signature, an example call, its arguments and its
  options, what it answers, its errors and its types, and its operation in the
  API reference, which links back.
- [Types](/docs/sdks/typescript/types): every type of the API the SDK names,
  its fields, and the methods that take or answer it.
- [Changelog](/docs/sdks/typescript/changelog): every release, newest first,
  and what it changed.

## Versions

A method's name is a promise: one is added in a minor version, and renamed or
removed only in a major one. A new operation in the API becomes a method in the
next release, so the reference here and the package can be a release apart.
