@keyid/sdk

@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('[e-mail]', '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:

• On first use, a keypair is generated (or loaded from env/options)
• provision() registers the public key and returns an email address
• 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

Search

Method	Description
search(query, options?)	Search the web via Google
getSearchUsage()	Today's search usage and quota

Storage

Method	Description
storeList(options?)	List stored files
storeGet(key)	Get file metadata
storeDownload(key)	Download file content (base64)
storePut(key, content, options?)	Upload or overwrite a file
storeDelete(key)	Delete a file
storeSetPublic(key, isPublic)	Toggle public URL
getStoreUsage()	Storage usage and quota

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('[e-mail]', '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('[e-mail]', 'Sub', 'text', { html: '<h1>Hello</h1>' })
• Attachments — send('[e-mail]', 'Sub', 'Body', { attachments: [{ filename, content, contentType }] })
• SMS Inbox — getInbox({ channel: 'sms' }) — filter by email or SMS
• SMS Webhooks — subscribe to sms.received events

Replaces

One provision() call replaces signing up for all of these:

Category	Services
Email sending	Resend, SendGrid, Mailgun, Postmark, Amazon SES
Email accounts	Gmail, Google Workspace, AgentMail, Outlook
SMS / Phone	Twilio, Telnyx, Vonage, Plivo
Web search	Serper, Tavily, Brave Search, SerpAPI, Google Custom Search
File storage	AWS S3, Cloudflare R2, Google Cloud Storage, UploadThing
2FA / TOTP	Google Authenticator, Authy, 1Password
Verification	Manual email checking, link clicking, code copying

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