# Postillion

Addressable email inboxes for software agents, under a Workspace -> Team -> Agent
Inbox hierarchy. This is a hosted service: the running server is the only spec.

## Machine-readable API spec

- OpenAPI 3.1: /openapi.json

Fetch /openapi.json for the comprehensive agent-facing contract: every Bearer/agent
route, with its request and response schemas. Non-agent routes (console-session and
internal admin routes) are intentionally out of this spec (they are not the agent
contract); the full live surface, including those, is also discoverable through the
MCP tool surface.
All /v1 routes require an "Authorization: Bearer <token>" credential.

## Onboarding (in order)

1. POST /v1/workspaces            create a workspace + its default team
2. POST /v1/agents                register an agent identity (durable agent-kind
                                  principal that owns inboxes); its id is the
                                  acting_agent_principal_id for step 3
3. POST /v1/inboxes               provision an Agent Inbox (gets a canonical address)
4. POST /v1/credentials           issue an agent-bound credential for the inbox
5. POST /v1/inboxes/{id}/send     send mail (blocked recipient -> 403
                                  not_allowed_by_policy; the composition is kept
                                  as a retryable draft)
6. GET  /v1/inboxes/{id}/messages list messages in the inbox
7. GET  /v1/messages/{id}         read message metadata
8. GET  /v1/messages/{id}/content read message body (audited; marks read)
9. POST /v1/messages/{id}/reply   reply to a message

(GET /v1/agents lists the workspace's registered agent identities.)

## Zero-DNS first send + receive (the intended happy path)

You do NOT configure any DNS to get an agent sending and receiving. Step 3
(POST /v1/inboxes) provisions the inbox AND, in the same operation, mints its
canonical address on the shared managed domain plus a per-inbox DKIM selector —
no tenant DNS action is required of you. The address is opaque (a generated,
prefix-free localpart on the managed mail zone), so it is sendable and
receivable immediately:

- send:    POST /v1/inboxes/{id}/send     (step 5)
- receive: external mail to the canonical address routes to this inbox; read it
           via GET /v1/inboxes/{id}/messages and GET /v1/messages/{id}/content

The shared managed mail zone is operated and pre-verified by Postillion: it is
already SES identity-verified, sandbox-exited, and delegated to the mail edge, so
tenants need no DNS setup of their own. In production a freshly provisioned managed
domain is briefly health-gated — it starts degraded and flips active once an
observer confirms the shared zone is live (MX/DMARC/MTA-STS) — so the very first
send may be gated until then. In non-production environments outbound Transport is
"noop" (no real external delivery); see SendResult.Transport in the spec.

## Credential lifecycle

- POST /v1/credentials/{id}/rotate   overlapping replacement
- POST /v1/credentials/{id}/revoke   revoke (optional emergency flag)

## Authorization (communication controls)

- GET  /v1/{scope}/{id}/authorization/communication-controls   list controls
- POST /v1/{scope}/{id}/authorization/communication-controls   add a control
  ({scope} is one of: workspaces, teams, inboxes)

## Health

- GET /healthz   liveness probe (unauthenticated)