@keyid/sdk

Free email addresses and phone numbers for AI agents. No signup. No human needed.

Your agent gets a real email address in 3 lines of code, with optional phone number on demand. Send, receive, reply, search — full email + SMS capabilities with zero registration, zero cost, zero human involvement.

KeyID.ai handles everything: domain management, rotation, reputation monitoring, deliverability, phone pool management. 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}`);

// Optionally request a phone number
const { phone } = await agent.requestPhone();
console.log(`Agent phone: ${phone}`);

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

// Send email
await agent.send('[email protected]', '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 | | requestPhone() | Request a phone number (opt-in, authenticated) | | getIdentity() | Full profile (email, phone, avatarUrl, bio, reputation score/tier) | | getAddresses() | List all addresses (current + historical) | | updateIdentity(options) | Update profile (displayName, avatarUrl, bio, websiteUrl, profilePublic) | | getReputation() | Get own reputation score (0-100), tier, factor breakdown | | getPublicProfile(agentId) | Get another agent's public profile (no auth required) | | recover(recoveryToken, newKeypair?) | Rotate keypair using recovery token |

Messages

| Method | Description | |--------|-------------| | getInbox(options?) | Fetch inbox with pagination, filtering, search, channel filter | | 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(draftId) | Send a draft |

Settings

| Method | Description | |--------|-------------| | getSignature() | Get email signature | | setSignature(signature) | Set email signature | | getForwarding() | Get forwarding settings | | setForwarding(forwardingAddress) | Configure email forwarding | | getAutoReply() | Get auto-reply/vacation settings | | setAutoReply(options) | Configure auto-reply |

Contacts

| Method | Description | |--------|-------------| | listContacts(options?) | List saved contacts | | createContact(options) | Create a contact | | getContact(contactId) | Get contact detail | | updateContact(contactId, options) | Update contact | | deleteContact(contactId) | Delete contact |

Webhooks

| Method | Description | |--------|-------------| | listWebhooks() | List webhooks | | createWebhook(url, events?, options?) | Create webhook | | getWebhook(webhookId) | Get webhook detail | | updateWebhook(webhookId, options) | Update webhook | | deleteWebhook(webhookId) | Delete webhook | | getWebhookDeliveries(options?) | Delivery history |

Verification

| Method | Description | |--------|-------------| | getLinks(messageId) | Extract links from a message | | getCodes(messageId) | Extract verification codes from a message | | followLink({ messageId?, linkIndex?, url? }) | Follow a verification link, returns final URL and redirects |

Persona

| Method | Description | |--------|-------------| | getPersona() | Get agent persona profile | | createPersona(data?) | Create persona profile | | updatePersona(data) | Update persona profile |

Registrations

| Method | Description | |--------|-------------| | addRegistration(data) | Log a service registration | | listRegistrations(options?) | List registrations with optional filters | | getRegistration(id) | Get registration by ID | | updateRegistration(id, data) | Update a registration | | deleteRegistration(id) | Delete a registration |

Vault

| Method | Description | |--------|-------------| | listVault() | List all vault entries (keys + metadata) | | getVaultEntry(key) | Get a vault entry by key | | putVaultEntry(key, value, opts?) | Store a value in the vault | | deleteVaultEntry(key) | Delete a vault entry |

Lists & Metrics

| Method | Description | |--------|-------------| | addToList(direction, type, entry) | Add to allow/blocklist | | removeFromList(direction, type, entry) | Remove from list | | getList(direction, type) | Get list entries | | getMetrics(options?) | Query usage metrics |

Features

• Scheduled Send — send('[email protected]', 'Sub', 'Body', { scheduledAt: '2025-01-01T10:00:00Z' })
• Full-Text Search — getInbox({ search: 'invoice' })
• Starred Messages — updateMessage(id, { isStarred: true })
• Auto-Reply — setAutoReply({ enabled: true, body: 'Out of office', endDate: '...' })
• HTML Email — send('[email protected]', 'Sub', 'text', { html: '<h1>Hello</h1>' })
• Attachments — send('[email protected]', 'Sub', 'Body', { attachments: [{ filename, content, contentType }] })
• SMS Inbox — getInbox({ channel: 'sms' }) — filter by email or SMS
• SMS Webhooks — subscribe to sms.received events

VS Code Extension

For a visual inbox experience during development, install KeyID Agent Inbox — manage agents, monitor inboxes, extract verification codes, and reply to emails directly in VS Code.

Requirements

• Node.js 18+
• No external dependencies

License

MIT