AI agents that interact with the real world need real email addresses. Whether your agent is signing up for services, receiving verification codes, or managing customer conversations — it needs its own inbox.
KeyID gives every agent a real email address in one API call. No human setup, no domain configuration, no API keys to provision upfront. Free for 1,000 accounts.
What you'll build
By the end of this tutorial, your AI agent will be able to:
- Self-provision a real email address
- Send and receive emails
- Extract verification codes automatically
- Complete website signups end-to-end
- Generate TOTP 2FA codes
Option A: MCP (Claude, Cursor, Windsurf)
If you're using an MCP-compatible client, you don't need to write any code. Just connect the KeyID MCP server.
Hosted (recommended — zero install)
Add this to your MCP client config:
{
"mcpServers": {
"keyid": {
"url": "https://keyid.ai/mcp"
}
}
}
That's it. Your agent now has access to 47 tools for email, SMS, verification, and signup workflows.
Local (stdio)
{
"mcpServers": {
"keyid": {
"command": "npx",
"args": ["-y", "@keyid/agent-kit"]
}
}
}
What your agent can do via MCP
Once connected, your agent gets tools like:
keyid_provision— get an email address instantly
keyid_get_inbox/keyid_get_message— read incoming mail
keyid_send/keyid_reply— send email
keyid_get_codes— extract OTP verification codes from a message
keyid_get_links/keyid_follow_link— extract and follow verification links
keyid_start_registration_session— begin a tracked signup flow
keyid_generate_totp_code— generate 2FA codes
It also comes with pre-built prompts for common workflows:
set-up-agent-communications → Provision email, get identity
complete-email-verification → Watch for code/link, extract it
run-signup-session → Full signup flow with browser state
autonomous-signup → Create persona, sign up, record result
fetch-latest-code → Get the newest verification code
triage-inbox → List messages, highlight urgent ones
Option B: JavaScript/TypeScript SDK
npm install @keyid/sdk
Provision an email
import { KeyID } from '@keyid/sdk';
const agent = new KeyID();
// One call — agent gets a real email address
const { email, agentId } = await agent.provision();
console.log(`Agent email: ${email}`);
// → [email protected]
No API key needed. The agent generates an Ed25519 keypair locally and authenticates via challenge-response.
Read the inbox
const { messages } = await agent.getInbox();
for (const msg of messages) {
console.log(`From: ${msg.from} | Subject: ${msg.subject}`);
}
// Search for specific emails
const results = await agent.getInbox({ search: 'verification' });
Extract verification codes
// Get OTP codes from a message
const { codes } = await agent.getCodes(messageId);
console.log(`Verification code: ${codes[0]}`);
// → 847291
Follow verification links
// Extract links and follow them server-side (SSRF-safe)
const { links } = await agent.getLinks(messageId);
const { finalUrl } = await agent.followLink({
messageId,
linkIndex: 0
});
Send email
await agent.send(
'[email protected]',
'Order inquiry',
'What is the status of order #12345?'
);
Complete a signup flow
// 1. Provision email
const { email } = await agent.provision();
// 2. Use the email to sign up on a website (via Playwright, Puppeteer, etc.)
await page.fill('#email', email);
await page.click('#submit');
// 3. Wait for verification email
const { messages } = await agent.getInbox();
const verificationEmail = messages.find(m =>
m.subject.includes('verify')
);
// 4. Extract the code
const { codes } = await agent.getCodes(verificationEmail.id);
// 5. Enter it on the website
await page.fill('#code', codes[0]);
await page.click('#verify');
Option C: Python SDK
pip install keyid
from keyid import KeyID
agent = KeyID()
# Provision
result = agent.provision()
print(f"Email: {result['email']}")
# Read inbox
inbox = agent.get_inbox()
for msg in inbox["messages"]:
print(f"{msg['from']}: {msg['subject']}")
# Extract verification code
codes = agent.get_codes(message_id)
print(f"Code: {codes[0]}")
# Send email
agent.send("[email protected]", "Hello", "Message body")
Real-world example: CrewAI email team
from crewai import Agent, Task, Crew
from keyid import KeyID
keyid = KeyID()
result = keyid.provision()
researcher = Agent(
role="Research Assistant",
goal="Find and summarize information via email",
backstory=f"You have your own email: {result['email']}"
)
task = Task(
description="Email [email protected] requesting API documentation",
agent=researcher
)
crew = Crew(agents=[researcher], tasks=[task])
crew.kickoff()
How it stays free
KeyID uses a shared domain pool. Agents get addresses on rotating domains that are managed for deliverability. When a domain's reputation degrades, it's rotated out and a fresh one takes its place.
This means:
No per-mailbox cost — domains are shared across agents
No domain management — KeyID handles DNS, DKIM, SPF, DMARC
No warm-up — domains are pre-warmed before going active
Free for 1,000 accounts — no credit card, no trial period
Competitors like AgentMail charge per mailbox. KeyID gives you the same capabilities at zero cost.
Signup sessions: held state for multi-step flows
When your agent is signing up for a service, things can get complicated — email verification, SMS codes, TOTP setup, CAPTCHAs. KeyID's signup sessions track the entire flow:
// Start a tracked registration
const session = await agent.startRegistrationSession({
service: 'github.com',
email: agent.email
});
// ... agent fills forms, triggers verification ...
// Artifacts (codes, links) are automatically matched to the session
const artifacts = await agent.getRegistrationArtifacts(session.id);
// Save browser state for later resumption
await agent.saveBrowserState(session.id, {
cookies: await page.context().cookies(),
url: page.url()
});
What's next
— source code, examples, SDK packages
— MCP server package
— Python SDK
KeyID is open-source and free for 1,000 agent accounts. Get started →
SOCIAL SHARE CARD GENERATOR