@keyid/sdk

Free email addresses for AI agents. No signup. No human needed.

Your agent gets a real email address in 3 lines of code. Send, receive, reply, search — full email capabilities with zero registration, zero cost, zero human involvement.

KeyID.ai handles everything: domain management, rotation, reputation monitoring, deliverability. Your agent just generates a keypair and calls provision().

Install

npm install @keyid/sdk
# or
yarn add @keyid/sdk

Quick Start

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

const agent = new KeyID();

// Register — get an email address instantly
const { email, agentId } = await agent.provision();
console.log(`Agent email: ${email}`);

// Read inbox
const { messages } = await agent.getInbox();

// Send email
await agent.send('user@example.com', 'Hello', 'Message body');

// Reply to a message
await agent.reply(messages[0].id, 'Thanks for your email!');

Authentication

KeyID uses Ed25519 challenge-response authentication. The SDK handles this automatically:

1. On first use, a keypair is generated (or loaded from env/options)
2. provision() registers the public key and returns an email address
3. All subsequent calls auto-authenticate via signed nonce exchange

// Option 1: Auto-generate keypair (default)
const agent = new KeyID();

// Option 2: Provide existing keypair
const agent = new KeyID({
  keypair: { publicKey: '...hex...', privateKey: '...hex...' }
});

// Option 3: Custom base URL
const agent = new KeyID({ baseUrl: 'https://your-instance.com' });

API Reference

Identity

| Method | Description | |--------|-------------| | provision() | Register agent, get email address | | getIdentity() | Get agent identity (email, domain, classification) | | getAddresses() | List all addresses (current + historical) | | getRecoveryToken() | Get recovery token for key rotation |

Messages

| Method | Description | |--------|-------------| | getInbox(options?) | Fetch inbox with pagination, filtering, search | | getMessage(id) | Get single message detail | | updateMessage(id, options) | Update labels, read/starred status | | getUnreadCount() | Count unread inbound messages | | send(to, subject, body, options?) | Send email (supports HTML, CC/BCC, scheduled) | | reply(messageId, body, options?) | Reply to a message | | replyAll(messageId, body, options?) | Reply-all | | forward(messageId, to, body?) | Forward a message |

Threads

| Method | Description | |--------|-------------| | listThreads(options?) | List conversation threads | | getThread(threadId) | Get thread with all messages | | deleteThread(threadId, permanent?) | Delete thread |

Drafts

| Method | Description | |--------|-------------| | createDraft(options) | Create a draft | | getDraft(draftId) | Get draft detail | | updateDraft(draftId, options) | Update draft | | deleteDraft(draftId) | Delete draft | | `sendDraft...