Skip to the documentation
Knowledge base

Typed SDKs

A TypeScript client first, then the rest.

Details

  • Published on npm and in use. @openemail/sdk is a complete, dependency-free TypeScript client, published as both ESM and CommonJS, with one method for every documented operation the API serves, plus the two unauthenticated meta endpoints a client generator needs, and the key read from OPENEMAIL_API_KEY, a 30-second per-attempt timeout, two retries, a per-call apiKey override for a process serving several workspaces, and emails.iterate() to page a list without writing the cursor loop. It runs on Node 18 and up, Workers, Deno, Bun and the browser. A key with the wrong prefix throws at construction rather than 401-ing on the first call; the check is a prefix and nothing more, so a well-formed key that has been revoked still fails on the wire.
  • It is held to the server by a parity check that reads the OpenAPI document on every build and fails if the two drift: a method pointing at an operation the spec does not have, a documented operation with no method, a scope list that does not match the one the operation requires, a namespace with methods and no entry in the reference, or a method that does not send the request its own manifest names. It prints what it proved, and today that reads 116 SDK methods covering all 104 documented operations. Two generator scripts stand beside it and refuse to emit an operation that is unclassified or written with an em dash. That is why the client is not a wrapper written after the fact. It cannot lag the API by a release.
  • What is missing is the release plumbing. The package is on npm, so bun add @openemail/sdk works, but there is no release workflow: publishing is a manual run of the preflight, the build and bun publish, which means a version reaches npm when somebody remembers rather than when the change lands. The API it defaults to is on and answering.
  • TypeScript is the only language, and the OpenAPI document is deliberately the answer for the rest rather than five hand-written clients that fall behind at different rates. There is no Python, Go or Ruby client in the repo, and there will not be one before the document is the thing they are generated from.