keyid
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
pip install keyid
Quick Start
from keyid import KeyID
agent = KeyID()
# Register — get an email address instantly
result = agent.provision()
print(f"Agent email: {result['email']}")
# Read inbox
inbox = agent.get_inbox()
for msg in inbox["messages"]:
print(f"{msg['from']}: {msg['subject']}")
# Send email
agent.send("[email protected]", "Hello", "Message body")
# Reply to a message
agent.reply(inbox["messages"][0]["id"], "Thanks!")
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)
agent = KeyID()
# Option 2: Provide existing keypair
agent = KeyID(public_key="...hex...", private_key="...hex...")
# Option 3: Custom base URL
agent = KeyID(base_url="https://your-instance.com")
API Reference
Identity
| Method |
Description |
provision() |
Register agent, get email address |
get_identity() |
Get agent identity info |
get_addresses() |
List all addresses (current + historical) |
get_recovery_token() |
Get recovery token for key rotation |
Messages
| Method |
Description |
get_inbox(**kwargs) |
Fetch inbox with pagination, filtering, search |
get_message(id) |
Get single message detail |
update_message(id, **kwargs) |
Update labels, read/starred status |
get_unread_count() |
Count unread inbound messages |
send(to, subject, body, **kwargs) |
Send email (HTML, CC/BCC, scheduled) |
reply(message_id, body, **kwargs) |
Reply to a message |
reply_all(message_id, body, **kwargs) |
Reply-all |
forward(message_id, to, body=None) |
Forward a message |
Threads
| Method |
Description |
list_threads(**kwargs) |
List conversation threads |
get_thread(thread_id) |
Get thread with all messages |
delete_thread(thread_id, permanent=False) |
Delete thread |
Drafts
| Method |
Description |
create_draft(**kwargs) |
Create a draft |
get_draft(draft_id) |
Get draft detail |
update_draft(draft_id, **kwargs) |
Update draft |
delete_draft(draft_id) |
Delete draft |
send_draft(draft_id) |
Send a draft |
Settings
| Method |
Description |
get_signature() |
Get email signature |
set_signature(text, html=None) |
Set email signature |
get_forwarding() |
Get forwarding settings |
set_forwarding(**kwargs) |
Configure email forwarding |
get_auto_reply() |
Get auto-reply/vacation settings |
set_auto_reply(**kwargs) |
Configure auto-reply |
Contacts
| Method |
Description |
list_contacts(**kwargs) |
List saved contacts |
create_contact(**kwargs) |
Create a contact |
get_contact(contact_id) |
Get contact detail |
update_contact(contact_id, **kwargs) |
Update contact |
delete_contact(contact_id) |
Delete contact |
Webhooks
| Method |
Description |
list_webhooks() |
List webhooks |
create_webhook(url, events=None) |
Create webhook |
get_webhook(webhook_id) |
Get webhook detail |
update_webhook(webhook_id, **kwargs) |
Update webhook |
delete_webhook(webhook_id) |
Delete webhook |
get_webhook_deliveries(**kwargs) |
Delivery history |
Lists & Metrics
| Method |
Description |
add_to_list(direction, type, entry) |
Add to allow/blocklist |
remove_from_list(direction, type, entry) |
Remove from list |
get_list(direction, type) |
Get list entries |
get_metrics(**kwargs) |
Query usage metrics |
Features
- Scheduled Send —
agent.send("[email protected]", "Sub", "Body", scheduled_at="2025-01-01T10:00:00Z")
- Full-Text Search —
agent.get_inbox(search="invoice")
- Starred Messages —
agent.update_message(id, is_starred=True)
- Auto-Reply —
agent.set_auto_reply(enabled=True, body="Out of office")
- HTML Email —
agent.send("[email protected]", "Sub", "text", html="<h1>Hello</h1>")
Requirements
- Python 3.9+
httpx (installed automatically)
License
MIT
