ujex-postbox 0.1.0

Official Python SDK for Ujex Postbox — email-for-AI-agents with built-in prompt-injection scoring, auth verdicts, and plus-addressed task threading.

ujex-postbox

The Python SDK for Ujex Postbox — email for AI agents.

pip install ujex-postbox

30-second demo

from ujex_postbox import PostboxClient, plus_address

client = PostboxClient(device_key="ap_live_...", agent_id="agent-hello")

# Send
resp = client.send(
    to=["[e-mail]"],
    subject="Re: invoice",
    body="On it — sending by Friday.",
    require_human=True,
)
print(resp.id, resp.status, resp.quota_remaining)

# Plus-address a per-task inbox (no new inbox needed)
addr = plus_address("[e-mail]", task_id="proj-42-abc")
# -> [e-mail]

# Read an inbound message
m = client.read_message(agent_id="agent-hello", message_id="msg_01...")
print(m.pi_score, m.pi_reasons, m.auth_verdict.dkim, m.plus_task_id)

Why not AgentMail / SES / SendGrid?

Postbox surfaces Ujex's agent-specific signals as first-class fields:

Field	What it gives you
m.pi_score / m.pi_reasons	Gemini-scored prompt-injection risk on every inbound, 0-1.
m.auth_verdict.dkim/spf/dmarc	RFC 5321/7208/7489 verdicts — bool per message, no parsing SPF strings yourself.
m.plus_task_id	Task id automatically extracted from the plus-address.
resp.quota_remaining	Per-agent monthly budget remaining in USD-equivalent units.
require_human=True on send	Returns waiting_approval; the outbound message dispatches after app/dashboard approval.

API

Method	Purpose
PostboxClient.send(to, subject, body, thread_key?, idempotency_key?, require_human?)	Send an email. Returns SendResult.
PostboxClient.list_messages(agent_id, direction?, limit?, since?)	List inbound or outbound messages. Returns list[Message].
PostboxClient.read_message(agent_id, message_id)	Full message with body + verdicts.
PostboxClient.list_inboxes(agent_id?)	Provisioned inboxes.
plus_address(base_inbox, task_id)	Build base+task@domain.
parse_plus_address(addr)	{base, task_id, domain} or None.
verify_signature(raw_body, signature, secret)	Timing-safe HMAC-SHA256 check on an inbound webhook.
parse_inbound_event(raw_body)	Raw bytes/dict → InboundEvent.

An AsyncPostboxClient mirrors the same surface on httpx.AsyncClient.

Retries

Retries automatically on 429 and 5xx with exponential backoff and respect for Retry-After. Default max 3 retries. Tune with PostboxClient(max_retries=…).

Webhook verification

from ujex_postbox import verify_signature, parse_inbound_event

ok = verify_signature(
    raw_body=request.body,                      # bytes
    signature=request.headers["x-ujex-signature"],
    secret=os.environ["POSTBOX_INGEST_SECRET"],
)
if not ok:
    return Response(status=401)
event = parse_inbound_event(request.body)
if event.injection_score.score > 0.7:
    # flag for review, don't let the agent process it yet
    quarantine(event)

Framework integrations

Each adapter is an opt-in install that raises a clear ImportError with install instructions if the framework isn't present.

LangChain

pip install 'ujex-postbox[langchain]'

from ujex_postbox import PostboxClient
from ujex_postbox.integrations.langchain import postbox_tools

client = PostboxClient(device_key="ap_live_...", agent_id="agent-hello")
tools = postbox_tools(client, agent_id="agent-hello")
# hand `tools` to any LangChain agent / graph

LlamaIndex

pip install 'ujex-postbox[llamaindex]'

from ujex_postbox import PostboxClient
from ujex_postbox.integrations.llamaindex import postbox_tools

client = PostboxClient(device_key="ap_live_...", agent_id="agent-hello")
tools = postbox_tools(client, agent_id="agent-hello")

CrewAI

pip install 'ujex-postbox[crewai]'

from ujex_postbox import PostboxClient
from ujex_postbox.integrations.crewai import postbox_tools

client = PostboxClient(device_key="ap_live_...", agent_id="agent-hello")
send_tool, read_tool, list_tool = postbox_tools(client, agent_id="agent-hello")

Core loop

Use Python for the Postbox edge of the golden path: send/receive agent mail, request human approval with require_human=True, and inspect prompt-injection signals on inbound messages. Recall memory and owner-scoped Audit are available through the dashboard, CLI, and TypeScript client while the Python SDK remains Postbox-focused.

No account yet?

Free tier: 100 sends/month plus approvals, audit, and Recall memory, no card. Sign up at ujex.dev.

License

Apache-2.0