hedwigbot 1.0.0

Official Python SDK for hedwig.bot

hedwigbot

Official Python SDK for hedwig.bot — real inboxes for AI agents.

Installation

pip install hedwigbot

Quick Start

from hedwigbot import Hedwig

client = Hedwig(api_key="your-api-key")

# Create an inbox
inbox = client.inboxes.create(
    email_address="support-agent",
    display_name="Support Agent"
)

print(f"Created inbox: {inbox['email_address']}")

# List messages
response = client.inboxes.messages(inbox["id"])
messages = response["messages"]

# Send a message
client.inboxes.send(
    inbox["id"],
    to="[e-mail]",
    subject="Re: Your question",
    body_text="Thanks for reaching out!"
)

Configuration

from hedwigbot import Hedwig

client = Hedwig(
    api_key="your-api-key",
    base_url="https://api.hedwig.bot"  # optional, defaults to production
)

API Reference

Inboxes

# List all inboxes
response = client.inboxes.list(limit=50, page_token="optional-cursor")
inboxes = response["inboxes"]
next_page = response.get("next_page_token")

# Create an inbox
inbox = client.inboxes.create(
    email_address="agent-123",      # optional, auto-generated if omitted
    display_name="Agent Name",       # optional
    metadata={"team": "support"}     # optional
)

# Get an inbox
inbox = client.inboxes.get("inbox_id")

# Delete an inbox
client.inboxes.delete("inbox_id")

# List messages in an inbox
response = client.inboxes.messages("inbox_id", limit=25)
messages = response["messages"]

# Get a specific message
message = client.inboxes.get_message("inbox_id", "message_id")

# Send a message
sent = client.inboxes.send(
    "inbox_id",
    to="[e-mail]",
    subject="Hello",
    body_text="Plain text body",
    body_html="<p>HTML body</p>",  # optional
    from_name="Custom Name",        # optional
    reply_to="[e-mail]"   # optional
)

# List threads
response = client.inboxes.threads("inbox_id", limit=20)
threads = response["threads"]

Webhooks

# List all webhooks
response = client.webhooks.list()
webhooks = response["webhooks"]

# Create a webhook
webhook = client.webhooks.create(
    url="https://yourapp.com/webhook",
    event_types=["message.received", "message.sent"]
)

# Get a webhook
webhook = client.webhooks.get("webhook_id")

# Delete a webhook
client.webhooks.delete("webhook_id")

API Keys

# List all API keys
response = client.api_keys.list()
keys = response["api_keys"]

# Create an API key
result = client.api_keys.create(
    name="Production Key",
    inbox_id="inbox_123"  # optional, for inbox-scoped keys
)

# Save the key immediately - it won't be shown again!
print(f"New API Key: {result['key']}")

# Revoke an API key
client.api_keys.revoke("key_id")

Error Handling

from hedwigbot import Hedwig, HedwigApiError

try:
    inbox = client.inboxes.create()
except HedwigApiError as error:
    print(f"API Error ({error.status}): {error}")
    print(f"Details: {error.details}")

Pagination

All list endpoints support cursor-based pagination:

page_token = None

while True:
    response = client.inboxes.list(limit=50, page_token=page_token)
    
    # Process inboxes
    for inbox in response["inboxes"]:
        print(inbox["email_address"])
    
    # Check for more pages
    page_token = response.get("next_page_token")
    if not page_token:
        break

Type Hints

The SDK includes complete type hints:

from hedwigbot import Hedwig
from hedwigbot.types import Inbox, Message, Webhook

client = Hedwig(api_key="your-key")

inbox: Inbox = client.inboxes.get("inbox_id")

Requirements

• Python 3.8+
• requests>=2.31.0

License

MIT

Support

• Documentation: https://docs.hedwig.bot
• Issues: https://github.com/gondar00/ai-mailbox/issues
• Email: [e-mail]