Python SDK
The official Python SDK provides simple, Pythonic access to the AgentInbox API with automatic retries and error handling.
Pythonic API
The Python SDK uses snake_case for all parameters and methods, following PEP 8 conventions.
Installation
Install the SDK via pip, pipenv, or poetry.
bash
pip install AgentInboxbash
pipenv install AgentInboxbash
poetry add AgentInboxConfiguration
Initialize the client with your API key.
Configuration
from AgentInbox import AgentInboxClient client = AgentInboxClient( api_key="at_live_...", # Optional: override base URL base_url="https://agentinbox.in", # Optional: configure retries max_retries=3,)Creating an Inbox
Creating an inbox
inbox = client.inboxes.create( ttl_seconds=3600, metadata={"workflow": "signup"},) print(inbox.id) # "inb_123"print(inbox.email_address) # "k3v9x2m4q7tz@agentinbox.in"print(inbox.expires_at) # datetime objectWaiting for Emails
Waiting for an OTP
wait = client.waits.create( inbox_id=inbox.id, type="otp", timeout_seconds=120,) if wait.status == "completed": print(wait.result.value) # "123456"elif wait.status == "timed_out": print("No OTP received within timeout")Error Handling
The SDK raises typed exceptions for different failure modes.
Error handling
from AgentInbox import AgentInboxError, RateLimitError, AuthenticationError try: inbox = client.inboxes.create(ttl_seconds=3600)except RateLimitError as e: print(f"Rate limited, retry after: {e.retry_after}")except AuthenticationError: print("Invalid API key")except AgentInboxError as e: print(f"API error: {e.message} (status {e.status_code})")except Exception as e: print(f"Unexpected error: {e}")Exception Types
- AuthenticationError — Invalid or missing API key
- RateLimitError — Rate limit exceeded, includes retry_after
- NotFoundError — Resource does not exist
- ValidationError — Invalid request parameters
- AgentInboxError — Base class for all API errors
Advanced Usage
Sessions and workflows
# Create a sessionsession = client.sessions.create(name="signup-flow") # Run a workflowworkflow = client.workflows.create_inbox_and_wait( wait_type="otp", timeout_seconds=120, session_id=session.id,) print(workflow.inbox.email_address)print(workflow.wait.result.value)