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("user@example.com", "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("to@x.com", "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("to@x.com", "Sub", "text", html="<h1>Hello</h1>")
Requirements
- Python 3.9+
httpx (installed automatically)
License
MIT