deaddropzone 0.3.0

Python SDK for DeadDrop — receive-only email inboxes for AI agents

DeadDrop Python SDK

Python client for the DeadDrop API — programmable email inboxes for the agentic era.

Install

pip install deaddropzone

The distribution name is deaddropzone (the deaddrop name on PyPI is taken), but the import name is still deaddrop:

from deaddrop import DeadDrop

Quick start

from deaddrop import DeadDrop

dd = DeadDrop(api_key="dd_live_...")

# Create an inbox
inbox = dd.create_inbox(slug="my-signup-test")
print(f"Send email to: {inbox.address}")

# Wait for an OTP (blocks until one arrives or timeout)
otp = dd.wait_for_otp(inbox.id, timeout=60)
print(f"Got OTP: {otp.value}")

# Wait for a verification link
link = dd.wait_for_link(inbox.id, "verification", timeout=60)
print(f"Verify at: {link.url}")

Ephemeral inboxes (no auth)

from deaddrop import DeadDrop

dd = DeadDrop()  # no API key needed
inbox = dd.create_ephemeral_inbox()
# inbox expires in 1 hour

Configuration

Parameter	Env var	Default
api_key	DEADDROP_API_KEY	—
base_url	DEADDROP_API_URL	https://api.deaddrop.zone

Convenience methods

The SDK provides high-level methods that compose the long-poll wait endpoint with extraction:

• wait_for_message(inbox_id, ...) — Block until a message arrives matching filters.
• wait_for_otp(inbox_id, ...) — Wait for a message with an OTP, return the highest-confidence match.
• wait_for_link(inbox_id, link_type, ...) — Wait for a message with a specific link type.

All accept optional timeout, after, subject_contains, and from_contains filters.

Inbox pools

pool = dd.create_pool("ci-tests", target_size=5)
inbox = dd.checkout_inbox(pool.id)
# ... use inbox ...
dd.return_inbox(pool.id, inbox.id)

Error handling

from deaddrop import DeadDrop, DeadDropError
from deaddrop.errors import TimeoutError

dd = DeadDrop(api_key="dd_live_...")

try:
    otp = dd.wait_for_otp(inbox_id, timeout=10)
except TimeoutError:
    print("No OTP arrived in time")
except DeadDropError as e:
    print(f"API error: {e.code} — {e.message}")

License

MIT