Skip to Content

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 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 need Node 22.12 or later or Bun.

Install

npm install @openemail/sdk

Its first release is 1.0.0.

Make a first call

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, the API's whoami, says what the key reaches. Keep the key on a server: The 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.

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 is the API's send, and messages.list its message listing, every page of it. (console.log stands for your own code.)

The guides

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

The reference

  • All methods: every namespace, each method with what it does and the operation it calls.
  • 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: every type of the API the SDK names, its fields, and the methods that take or answer it.
  • 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.