Python email API and webhook examples for AI agents

Download the tested starters

Download the Python starter bundle. It contains an inbox API client, a local webhook receiver, integration tests and a README. Extract it into a working directory you control.

The examples are source code you can adapt, not a hosted agent runtime or a production queue service. The website does not run the Python files.

Run the tests without an account or domain

python3 -m unittest discover -s examples/python -p '*_test.py' -v

The tests start local HTTP servers and use temporary databases. They check request authentication, cursor encoding, idempotency keys, redirects, raw-body signature verification, duplicate events and retryable persistence failures. They do not send email or contact a provider.

Read an inbox and send a controlled test

Create an inbox and selected-inbox key in Outflare. Set AGENT_MAIL_BRAND_ID, AGENT_MAIL_INBOX_ID and AGENT_MAIL_KEY through your environment or secret manager. Read permission is required for listing; sending needs send permission.

python3 examples/python/agent_mail.py messages
python3 examples/python/agent_mail.py messages --after YOUR_NEXT_CURSOR

The output can contain private email content. Keep it local. To send one message, replace the example address with a recipient you control:

python3 examples/python/agent_mail.py send \
  --to recipient@example.com \
  --subject 'Controlled test' \
  --text 'Hello from my agent inbox.' \
  --idempotency-key controlled-test-001

There are no automatic retries. Reuse the key only for an identical intended message. Investigate unknown outcomes before sending again. Real requests require an active, configured Agent Mail service.

Queue verified webhook events locally

Provide the signing secret for your Outflare webhook endpoint in AGENT_MAIL_WEBHOOK_SECRET. The receiver only needs that secret; it does not need an inbox API key.

python3 examples/python/webhook_receiver.py \
  --database agent-mail-events.sqlite --port 8787

It listens on loopback at /webhooks/agent-mail. For a live development test, expose it through an approved HTTPS tunnel and register that HTTPS URL in Outflare. No tunnel or cloud deployment is included.

The receiver checks the original signed bytes, commits event metadata, and then acknowledges. Duplicates do not create another queue record; a queue failure returns a retryable error. It never logs the raw request or sends a reply.

Add your agent behind the queue

Add a separate worker to fetch the message using a scoped read key and run your own agent logic. Treat email bodies and attachments as untrusted content. Do not grant sensitive actions solely because an email asks for them.

Before production use, add durable processing state, worker leases, retries, monitoring, restricted storage and a tested recovery procedure. The receiving skeleton intentionally stops at a committed queue record; it does not claim to be an autonomous replying agent.