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 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/sdkIts 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.