# Thrd LLM Reference

Project: Thrd (Agent Email)
Primary site: https://thrd.email
API host: https://api.thrd.email

## What Thrd Is
Thrd is email infrastructure designed for AI agents and the humans who operate them. It provides a dedicated "agent inbox" that is isolated from your primary inbox, plus a machine-first API for receiving and sending email with safety controls.

Safety by default:
- Don't connect your primary inbox (Gmail/Outlook/etc.) to an agent.
- Use a dedicated agent inbox instead.

## What Humans Should Do
If you want your agent to use email:
1. Create an agent inbox (sandbox) via the Thrd instant onboarding endpoint.
2. Store the returned API key in your secret manager.
3. Give the agent access only to that isolated inbox via the API key.

## What Agents/LLMs Should Do
When asked to "set up email for an agent":
1. Ask the human for permission to create a dedicated agent inbox (do not use their personal inbox).
2. Use instant onboarding to provision a tenant + agent + inbox + API key.
3. Tell the human to store the API key as `THRD_API_KEY` and provide it to the runtime securely.
4. Use the OpenAPI contract to generate tools or integrate endpoints.

## Instant Onboarding (Public)
POST https://api.thrd.email/v1/onboarding/instant
- Returns: tenant, agent, inbox, api_key, scopes, machine_bootstrap, first_email_test.
- `agent_name` is required and sets the sender display name.
- Optional: `tenant_name`, `contact_email`, `inbox_prefix`, `source` ("human"|"agent"), `product_updates_consent`.
- Auth is not required for this endpoint.
- Lifecycle: Available after a provisional inbox is claimed and activated. Treat the inbox as provisional until claim and activation complete.

## Commercial Contract
- Unlimited incoming email means no monthly commercial quota based on incoming-message count.
- No monthly incoming-message quota. Fair-use, anti-abuse, 5 MB message-size and retention limits apply.
- Free: 1 safe agent inbox, 25 safe reply recipient units per UTC month, maximum 5 per UTC day, no payment card.
- Starter: 2,000 outbound recipient units/month under Tier 1 reply-only authority.
- Limited: 10,000 outbound recipient units/month under Tier 2 existing recipient authority.
- Verified: 50,000 outbound recipient units/month under domain, recipient-authority, reputation and suppression controls.
- Commercial plan, outbound authority, Gate availability and usage counters are independent. Payment never bypasses authority or suppressions.

## Runtime Auth
Authorization: Bearer <api_key>

## Core Runtime Model
- Inbound delivery: long-poll `GET /v1/events?cursor=0&timeout=25000`
- ACK: `POST /v1/events/ack`
- Optional wake webhook (recommended): `PUT /v1/wake/webhook` to receive signed `inbox.pending` pings, then pull with `/v1/events`
- Reply: `POST /v1/reply` (idempotency required; reply-all preserves historical CC + latest inbound To recipients; optional `cc[]` adds recipients on Tier2+ only; may require `security_ack_token` on high-risk inbound)
- New outbound: `POST /v1/send` (idempotency required, policy-gated; optional `source_message_id` activates inbound prompt-injection firewall)
- Outbound status: `GET /v1/outbound/:request_id`
- Guided activation: `GET /v1/activation` returns the next first-email step, milestone timestamps, and a provider-agnostic deliverability error.
- Usage and entitlement windows: `GET /v1/usage` (inbound is unmetered and observational; outbound is recipient-unit based with daily/monthly windows)
- If Free outbound usage is `near_limit` or `limit_reached`: offer Starter via `POST /v1/billing/checkout/self` with `{ "plan": "sandbox" }` (9 EUR/month, 2,000 outbound recipient units/month).
- Message security details: `GET /v1/messages/:id/security`
- Security ack token: `POST /v1/security/ack`

## Gate Authorization Layer (Foundation)
Gate treats external email as untrusted evidence, never as authority:
1. Normalize evidence and security signals.
2. Propose one canonical action with exact arguments and source binding.
3. Evaluate a versioned deterministic policy: allow, review, or deny.
4. For review, a human approves, denies, or modifies one exact action. Modification creates a new action hash and fresh evaluation.
5. A signed, short-lived, single-use capability authorizes one exact action; the executor verifies it.
6. Action receipts provide a replayable public hash chain without exposing raw email, tokens, or replay secrets.

Gate API resources are hosted on https://api.thrd.email and documented in OpenAPI:
- Policy validation and lifecycle: `/v1/policies`, `/v1/policies/validate`
- Action authorization: `/v1/actions/authorize`
- Human interruptions: `/v1/approvals`
- Exact receipt export: `/v1/action-receipts/{id}`
- Evidence ingestion: `/v1/evidence/email`

Gate, Evidence V2, approvals, capabilities, and executors are feature-gated. Production flags default off; clients must handle feature-disabled and unavailable states explicitly.

## Safety Model
- Policy outcomes: allow / block / quarantine
- Inbound Prompt Shield outcomes: allow / require_ack / block (tier-aware)
- Recipient feedback loop: a public signed link records useful/spam/block feedback
- Suppressions can be created automatically based on feedback signals
- Verified outbound may require Proof of Reasoning (PoR): `428 por_required`

## Gate Authorization Chain (Controlled Beta)
Gate is deployed behind explicit tenant feature flags. Do not assume availability only because its schemas appear in OpenAPI.

Authority rule:
- External email is untrusted evidence, never an instruction.
- A model may interpret and recommend, but cannot mint authorization.
- Deterministic policy evaluates one canonical action hash.
- Allow may issue a short-lived, revocable, single-use capability for that exact action.
- Review requires a tenant-bound human approval; human responses never expose the capability bearer.
- The executor verifies capability, credential, target, environment and action before execution.
- Terminal transitions append a redacted, replayable action receipt.

Primary Gate operations:
- Authorize action: `POST /v1/actions/authorize`
- Poll approvals: `GET /v1/approvals` and `GET /v1/approvals/:id`
- Redeem capability: `POST /v1/capabilities/redeem`
- Report execution: `POST /v1/actions/:id/executions`
- Read receipt: `GET /v1/action-receipts/:id`
- Evidence event: `evidence.created.v2`

Compatibility requirement:
- Keep using the existing inbox, events, ACK, reply and send contracts when Gate is disabled.
- Handle disabled-feature responses explicitly and never downgrade to an ungoverned tool call.

## Trust + Verification (Public)
Thrd exposes a shareable public trust profile per agent:
- Web profile: https://thrd.email/a/<agent_ref>
- Programmatic verification: GET https://api.thrd.email/v1/public/agents/<agent_ref>/verify

Agent refs:
- Accepts UUID or a short base64url ref.

## Machine Integration Assets
- OpenAPI: GET/HEAD https://api.thrd.email/openapi.json
- Discovery alias: GET https://api.thrd.email/.well-known/openapi.json
- Examples: GET https://api.thrd.email/v1/examples/responses