@keyid/sdk: agent email addresses from an Ed25519 keypair

The signup form is the problem @keyid/sdk removes

Most email APIs assume a human already exists. You sign up, verify a phone number, generate an API key in a dashboard, and paste it into the agent. That works until the agent is the thing being deployed, at which point the human step is the bottleneck and the API key is a long-lived secret sitting in an environment variable.

@keyid/sdk targets the other case: an agent that needs an address it can own. The README states the pitch directly, calling it free email addresses for AI agents with no signup and no human needed, and says the agent gets a real email address in three lines of code. The unit of identity here is a keypair, not an account. The package itself is small, a TypeScript client published as @keyid/sdk with dist/index.js as the entry point.

The intended user is the person writing an autonomous agent in Node.js who needs inbound mail, outbound mail, or both, and who does not want to route that through a human-owned mailbox. If your agent only ever sends notifications to your own team, this is heavier than a webhook to Slack. The interesting case is an agent that must receive a reply, search an inbox, or hold a conversation thread.

How the Ed25519 challenge-response flow works

The authentication model is the part worth understanding before you install anything. According to the README, KeyID uses Ed25519 challenge-response authentication and the SDK handles it automatically. The sequence it describes has three steps: on first use a keypair is generated or loaded from env or options, provision() registers the public key and returns an email address, and all subsequent calls auto-authenticate via a signed nonce exchange.

That means the private key never leaves the client. The server stores a public key and challenges the client to sign a nonce. There is no bearer token to leak in a log line, which is a genuine improvement over the API-key pattern for long-running agents.

The client also accepts an existing keypair, so you can persist one yourself and skip regeneration. The README shows the option as an object with publicKey and privateKey fields in hex. It also accepts a baseUrl option, which implies the SDK is not hard-wired to one host, though the README does not describe how you would run a compatible server yourself.

The API surface beyond authentication is broad and conventional: identity, messages, threads, drafts, settings, contacts, webhooks, allow and blocklists, and metrics. The README documents send, reply, replyAll, forward, getInbox with pagination and search, and updateMessage for labels and read or starred status. Webhooks have their own lifecycle plus a delivery history call, which is the piece most email clients forget.

Installing @keyid/sdk and sending a first message

The README gives npm and yarn as the two install paths. Node.js 18 or higher is required, and the package declares no runtime dependencies, so the install pulls down the TypeScript client and its types and little else.

npm install @keyid/sdk

A minimal program needs three things: construct the client, call provision(), and use the returned address. The README's quick start does exactly this. The destructured result carries email and agentId, and the email value is what you print or store.

import { KeyID } from '@keyid/sdk';

const agent = new KeyID();
const { email, agentId } = await agent.provision();
console.log(`Agent email: ${email}`);

Once provisioned, the same client reads the inbox and sends. The README's example fetches messages, then replies to the first one by id, which is the shape most agents will need: read, decide, respond.

const { messages } = await agent.getInbox();
await agent.send('[email protected]', 'Hello', 'Message body');
await agent.reply(messages[0].id, 'Thanks for your email!');

If you would rather control the key material, pass a keypair to the constructor instead of letting the SDK generate one. The README lists this as option two, alongside a custom baseUrl as option three.

const agent = new KeyID({
  keypair: { publicKey: '...hex...', privateKey: '...hex...' }
});

After provision() returns, call getRecoveryToken() and store the result somewhere durable. The README lists the method under Identity as the recovery token for key rotation, and it is the only documented path back to an identity if the private key is lost.

Where the repository is thin

The repository is a client. The top level holds .github/, README.md, dist/, package.json, src/ and tsconfig.json. There is no server, no infrastructure configuration, no test suite visible in the listing, and no LICENSE file at the root even though package.json declares MIT and the README repeats it. For a package that asks you to hand it an agent identity, the absence of a licence file is a small but real friction point for anyone whose legal review wants the actual text in the repository.

More importantly, the README does not document what happens to an address when you stop calling the API, how long messages are retained, or what limits apply to sending volume. It mentions that KeyID.ai handles domain management, rotation, reputation monitoring and deliverability, which is a claim about the hosted service rather than anything you can inspect in this repository. There is no published rate limit anywhere in the published documentation, and no description of what the free tier actually caps.

The last push to the repository was on 2026-06-19, and the most recent release listed is v0.2.0 from 2026-03-13. The version number is the honest signal here: a 0.2.0 client with a broad API surface is early, and the README's method tables are the specification you have. Treat the API as subject to change.

One more gap: the README says the SDK handles challenge-response automatically but does not document the nonce exchange itself, so if the hosted endpoint changes behaviour you have no client-side specification to check it against.

When @keyid/sdk is the wrong tool

If deliverability is the product you are buying, understand that you are buying it from KeyID.ai, not from this package. The SDK is a thin client over a hosted service. Self-hosting is not described in the README; the baseUrl option suggests the possibility of pointing at another instance, but nothing in the repository tells you how to run one. An agent that must operate inside your own network boundary, or that must send from your own domain with your own DKIM keys, is not served by this package as documented.

Language coverage is the other boundary. This is the JavaScript and TypeScript SDK. An agent written in Python, Go or Rust has no client here, and the README does not point to one.

There is also a governance question that the README does not answer. An agent that provisions its own address and holds its own private key is an agent whose mail you may not be able to read. That is the point of the design, and it is also why some teams will not be allowed to use it. If your compliance process requires that all outbound mail be logged centrally with the plaintext body, you need to build that logging yourself on top of send().

Finally, the free framing deserves scrutiny. The README says zero cost, and the service is described as free for agents. Nothing published describes a paid tier, a quota, or what happens when a quota is reached, so you cannot plan capacity from what is documented.

Alternatives and the difference in approach

The closest comparison is a transactional email provider with a REST API and an official Node client. The difference is where identity comes from. With a provider like that, you create an account, verify a sending domain, and receive a long-lived API key; the SDK is a typed wrapper over HTTP calls that carry that key. @keyid/sdk replaces the account with a keypair and the API key with a signed nonce, and it gives the agent an inbox rather than only a send endpoint. If your agent needs to receive and search mail, the provider route means you also build inbound parsing, storage and a webhook handler.

A second option is a general-purpose IMAP and SMTP client against a mailbox you already own. That gives you full control, no third party in the message path, and no new vendor. It also means you manage the credentials, the connection lifecycle, the MIME parsing and the spam exposure yourself, and you cannot hand an agent a mailbox without a human having created it first. The README's central claim, no human needed, is precisely what that approach cannot offer.

A third route is running your own mail server. That is a different project with a different cost profile, and the README's mention of domain rotation and reputation monitoring is a reminder of how much operational work sits behind an address that reliably lands in an inbox.

Maintenance cost and what the MIT label does and does not cover

The upgrade surface is small. The package has two dev dependencies, @types/node and typescript, and its build script is tsc with a prepublishOnly hook that runs the build. There is no bundler, no test runner and no lint configuration in package.json, so upgrading means reading the README's method tables against the installed version and checking that the methods you call still exist. At 0.2.0, pin the version in your lockfile rather than floating on a caret range.

The MIT declaration in package.json and the README covers the client code. It does not cover the hosted service. Using @keyid/sdk means your agent's mail flows through KeyID.ai infrastructure, and the repository contains no terms of service, no privacy policy and no data processing description. That is the gap to close before adoption, and it is a question for the vendor rather than something a licence identifier answers. This is not legal advice; if your organisation has a review process for third-party data flows, the repository gives that process almost nothing to work with.

The operational cost that is easy to miss is key custody. If you let the SDK auto-generate the keypair, the private key lives in the process. Restart the process in a fresh container and you have a new identity unless you passed a keypair in. The getRecoveryToken() method exists for rotation, and the README does not describe the rotation procedure itself, so test that path deliberately rather than discovering it during an incident.

Editorial conclusion

Adopt @keyid/sdk if your agent needs a mailbox and no human can complete a signup form; the provision() call and the Ed25519 challenge-response flow are documented and the package declares no runtime dependencies. Do not adopt it if you need a written retention or deletion policy, a published SLA, or a client in a language other than JavaScript, because the repository contains one TypeScript package and nothing else. Before wiring it into anything that matters, call provision(), then getRecoveryToken(), and store that token somewhere outside the process that holds the private key.

Frequently asked questions

Official sources

1. Issues
2. KeyID-AI/sdk-js on GitHub
3. Project website
4. README
5. Releases