KeyID Python SDK: Email Addresses for AI Agents Without Signup

What keyid solves for agents that need a mailbox

Most email providers assume a human at the keyboard. You sign up, confirm an address, pass a CAPTCHA, and pick a plan. An autonomous agent cannot do any of that, so it either borrows a human's mailbox or goes without. keyid targets that gap directly: the README's first line is "Free email addresses for AI agents. No signup. No human needed." The intended user is a developer wiring an agent that has to receive a verification link, answer a support thread, or hold a conversation over ordinary email. The SDK's own scope is narrow. It is a client library, not a mail server. KeyID.ai manages domains, rotation, reputation monitoring and deliverability, per the README, and the Python package is the surface your code touches. That division matters when you evaluate it: you are adopting a service, and the package is the handle.

Ed25519 challenge-response and the provision() data flow

Authentication is the part worth understanding before you write any code. There is no API key string to paste into an environment variable. On first use the SDK generates an Ed25519 keypair, or loads one you supply. Calling provision() registers the public key with the service and returns an email address. Every later call signs a nonce the server issued, which proves possession of the private key without transmitting it. The README describes this as "signed nonce exchange" and says the SDK handles it automatically. Two practical consequences follow. First, the private key is the account. Lose it and you lose the identity, which is why get_recovery_token() exists and is described as being for key rotation. Second, because the package depends on cryptography>=41.0 alongside httpx>=0.25, key generation happens locally in your process. Nothing in the README states where the generated key is persisted by default, so treat that as an open question and pass your own key material if the answer matters to you. The rest of the API is conventional: identity and address lookups, messages, threads, drafts, settings, contacts, webhooks, allow and block lists, and a metrics query. The method names map closely to mail concepts, so there is little to learn beyond the auth handshake.

Install keyid and send your first agent email

The package installs from PyPI under the name keyid and requires Python 3.9 or newer. The README gives a single-line install command, and httpx comes in as a dependency automatically.

pip install keyid

After that, the quick start is three concepts: construct the client, provision an address, then read or send. Constructing KeyID() with no arguments triggers local keypair generation. The provision call returns a dictionary whose email key holds the new address, so print it and keep it somewhere you can find it again.

from keyid import KeyID

agent = KeyID()
result = agent.provision()
print(f"Agent email: {result['email']}")

Receiving is a paginated inbox fetch. Each message in the returned messages list carries from, subject and an id you can pass back to reply.

inbox = agent.get_inbox()
for msg in inbox["messages"]:
    print(f"{msg['from']}: {msg['subject']}")

agent.reply(inbox["messages"][0]["id"], "Thanks!")

Sending takes a recipient, a subject and a body. Optional keyword arguments cover HTML bodies, CC and BCC, and scheduled_at for a future delivery time, as in agent.send("[email protected]", "Sub", "Body", scheduled_at="2025-01-01T10:00:00Z"). If you already have a keypair, pass public_key and private_key as hex strings to the constructor; if you run against your own instance, pass base_url. The README does not document what a failed provision returns, so wrap the first call and inspect the exception before you build on it.

Where the SDK stops and the hosted service begins

This is the limitation that shapes every other decision. The package contains no mail transfer agent, no MX handling and no domain configuration. Provisioning an address is a request to KeyID.ai, and the README attributes domain management, rotation, reputation monitoring and deliverability to that service. If KeyID.ai is unreachable, or an address is retired, your agent's mailbox goes with it. Nothing in the README describes a data export path, a retention window, or what happens to stored messages when an address rotates. For an agent that receives password resets or one-time codes, that is a real operational risk to weigh, not a hypothetical one. The same applies to volume. get_metrics() exists for querying usage, and add_to_list() and remove_from_list() let you manage allow and block entries, but the README states no sending quotas, no rate limits and no pricing terms beyond the word free. Absence of a documented limit is not the same as absence of a limit. If your agent sends in bulk, confirm the ceiling before you depend on it. Finally, the repository lists an MIT licence in pyproject.toml and under License in the README, while the repository metadata itself carries no licence identifier. Treat the discrepancy as something to confirm rather than assume.

keyid against a transactional email API

The obvious alternative for an agent that only needs to send is a transactional email provider such as SendGrid, Postmark or Amazon SES. The difference in approach is the direction of the mailbox. A transactional API is send-only and account-bound: you register a domain, verify DNS records, hold an API key, and you cannot receive a reply into the same system without extra work. keyid is bidirectional and self-provisioning. The agent creates its own address and can then read what comes back, search the inbox with get_inbox(search="invoice"), star messages, build threads and reply. That round trip is the thing a send-only API cannot do without bolting on an inbound parsing service. The trade is control. With SES or Postmark you own the domain and the reputation, and you can move providers without changing your address. With keyid you get the address instantly and hand the domain, the rotation and the reputation to someone else. If your agent must send from your company domain, keyid is the wrong shape. If it needs a disposable identity that can hold a conversation, the self-provisioning model is the point.

Maintenance status and what an upgrade costs you

The last push to the repository was on 2026-03-13, and the most recent release, v0.1.2, is dated 2026-03-13 as well. That is roughly six months before today, so the project is not in a state you should describe as actively developed on the strength of these facts alone. The version number tells the same story: 0.1.x signals a young API, and the method surface is broad for that stage, covering identity, messages, threads, drafts, settings, contacts, webhooks and lists. A wide surface at a low version number is a reasonable bet that some signatures will shift before 1.0. Upgrading means reading the release notes rather than trusting semver, and pinning the version in your requirements so a patch release cannot change behaviour under a running agent. There is no changelog content beyond the version tags themselves. The dependency footprint is small, httpx and cryptography, both with lower bounds rather than upper bounds, which is normal but means a future major release of either could break the SDK. Run the package in its own virtual environment so that upgrade is a deliberate act.

Editorial conclusion

Adopt keyid when an autonomous agent needs a mailbox it can create itself, with no signup step and no human in the loop, and when you are comfortable that the address, the domains and the deliverability work all live with KeyID.ai rather than with you. Do not adopt it when the mailbox must outlive the vendor, when you need a documented data-retention or rate-limit guarantee, or when the agent only ever needs to send notifications that a transactional email API already handles. Before committing, verify three things: that the MIT licence in pyproject.toml is the licence you are actually bound by, that get_recovery_token() output is stored somewhere outside the agent process so a lost key does not strand the address, and that get_metrics() gives you the sending volume you need to see. The SDK is a client, so the address is only as durable as the service behind it.

Frequently asked questions

Official sources

1. Issues
2. KeyID-AI/sdk-py on GitHub
3. Project website
4. README
5. Releases