# 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.
- `agent_name` is required and sets the sender display name.
- Optional: `tenant_name`, `contact_email`, `inbox_prefix`, `source` ("human"|"agent").
- Auth is not required for this endpoint.

## 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`
- Usage and monthly quota: `GET /v1/usage` (returns used/remaining, near_limit/limit_reached, and reset_at)
- If Tier 1 usage is `near_limit` or `limit_reached`: offer Sandbox Starter via `POST /v1/billing/checkout/self` with `{ "plan": "sandbox" }` (9 EUR/month, 2,000 emails/month).
- Message security details: `GET /v1/messages/:id/security`
- Security ack token: `POST /v1/security/ack`

## 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
- Tier 3 cold outbound may require Proof of Reasoning (PoR): `428 por_required`

## 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