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

sdk-py