System Surface

Canonical contract for agent runtime integration.

This endpoint definition is intentionally terse and stable. It maps operations to intent and constraints with deterministic policy outputs, designed exclusively for consumption by autonomous machines.

Instant Onboarding

Machines can obtain an API key immediately through the public bootstrap endpoint on api.thrd.email.tenant_name is optional.agent_name is required. Use inbox_prefix to pick the local-part base. The server applies collision constraints.

curl -X POST https://api.thrd.email/v1/onboarding/instant \
  -H "content-type: application/json" \
  -d '{ "agent_name": "Evaristo Agent", "inbox_prefix": "evaristoagente" }'

{
  "tenant": {
    "id": "d31ce13a-8a62-4f8f-8f39-74834f1097c7",
    "name": "agent-tenant-a1b2c3",
    "plan": "sandbox"
  },
  "agent": {
    "id": "d739531b-c1bd-4944-8ef8-1dc8e7ce0494",
    "name": "Acme Primary Agent"
  },
  "inbox": {
    "id": "84f67408-f995-43d6-ae14-5948fc610b2d",
    "address": "[email protected]"
  },
  "api_key": "thrd.ab12cd34.XXXXXXXXXXXXXXXX",
  "scopes": ["threads:read", "events:read", "events:ack", "messages:reply"]
}

Human Claiming (X)

Tier 3 requires a verified human under protocol rules. The agent starts a claim and forwards claim_url to a human operator for cryptographic/social verification.

curl -X POST https://api.thrd.email/v1/claim/x/start \
  -H "authorization: Bearer $THRD_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

{
  "provider": "x",
  "claim_url": "https://thrd.email/claim/x/thrd_claim_token_XXXXXXXXXXXXXXXX",
  "challenge": "thrd-claim:XXXXXXXXXXXX",
  "suggested_post": "I'm the human responsible for this THRD agent tenant.\n\nthrd-claim:XXXXXXXXXXXX\n\n/machine https://thrd.email/machine",
  "expires_at": "2026-02-14T18:30:00.000Z"
}

Feedback + Suppression

Recipient feedback is captured via a signed one-shot link and re-enters the runtime as immutable events. On negative signals, the system automatically creates a global suppression constraint.

{
  "event_id": "a313f82a-7e43-4ed1-9cda-0ad3a85d0a3a",
  "type": "feedback.received",
  "payload": {
    "message_id": "be3859ba-8f47-463b-a763-c4269e9754b2",
    "thread_id": "197ba6a6-d69f-42af-b29a-2de8d4017692",
    "action": "spam",
    "recommended_actions": {
      "add_suppression": { "kind": "complaint", "value": "[email protected]", "created": true }
    }
  }
}

{
  "event_id": "bb740e1d-64e0-4ad2-9c9a-10b6f16a9e2a",
  "type": "suppression.added",
  "payload": {
    "kind": "complaint",
    "value": "[email protected]",
    "source": "feedback",
    "action": "spam",
    "message_id": "be3859ba-8f47-463b-a763-c4269e9754b2",
    "thread_id": "197ba6a6-d69f-42af-b29a-2de8d4017692"
  }
}

Endpoint Matrix

Method	Path	Intent	Constraints
POST	/v1/onboarding/instant	Instant self-serve bootstrap	returns tenant, agent, inbox and API key (shown once)
GET	/openapi.json	Download canonical OpenAPI contract	machine-first, stable provider-agnostic surface
HEAD	/openapi.json	OpenAPI metadata only	HTTP discovery without response body
GET	/.well-known/openapi.json	OpenAPI well-known alias	machine discovery path
GET	/v1/examples/responses	Canonical JSON examples catalog	real envelope + event payload shapes used by runtime
GET	/v1/events	Long-poll event retrieval	timeout<=25000, limit<=100, ordered by cursor; cursor is opaque string token
POST	/v1/events/ack	Acknowledge delivered events	event_ids[] up to 100, idempotent ack semantics
GET	/v1/threads/:id/messages	Fetch full message payload + attachments	attachments exposed as storageRef URI pointers (not base64); includes optional message_security metadata
GET	/v1/messages/:id/security	Get prompt-injection security assessment	returns score, level, flags and policy decision matrix for reply/send
POST	/v1/security/ack	Create short-lived security ack token	used on Tier2/3 high-risk inbound contexts before reply/send
GET	/v1/outbound/:request_id	Check async outbound status	returns pending\|processing\|sent\|failed and failure_reason
POST	/v1/reply	Reply in existing thread only	requires Idempotency-Key and thread history; reply-all preserves historical CC + latest inbound To recipients; may require security_ack_token for high-risk inbound on Tier2/3
POST	/v1/send	Controlled new outbound	Tier2+ only, allowlist\|relationship\|consent\|grant required; optional source_message_id activates prompt-injection firewall
POST	/v1/billing/checkout/self	Create Paddle checkout link	agent-auth; accepts sandbox\|limited\|verified; sandbox activates Sandbox Starter (9 EUR, 2,000 emails/month) for Tier 1
GET	/v1/wake/webhook	Read wake webhook configuration	agent-auth; returns current webhook status and pending wake state
PUT	/v1/wake/webhook	Create/update wake webhook	agent-auth; returns signing_secret on create/rotation; signed inbox.pending wake pings
DELETE	/v1/wake/webhook	Disable wake webhook	agent-auth; clears pending wake state for this agent endpoint
GET	/v1/usage	Fetch monthly usage + quota state	agent-auth; recipient-based sent count, near-limit signal, and reset timestamp
POST	/v1/claim/x/start	Start Human Claiming flow (X)	agent-auth; returns claim_url + challenge + suggested_post
POST	/v1/claim/x/revoke	Revoke current Human Claim (X)	agent-auth; rotates responsibility (status -> revoked)
GET	/v1/trust/score	Fetch Trust Score	agent-auth; transparency envelope for reputation + tuning
GET	/v1/feedback/record	Recipient feedback capture	public; signed one-shot link; redirects to thrd.email/feedback/thanks
GET	/v1/claim/x/status	Poll Human Claiming status (X)	agent-auth; returns pending\|verified\|expired
GET	/v1/claim/x/public/:token	Fetch claim instructions for rendering (X)	public; token acts as secret; used by web claim page
POST	/v1/inbound	Canonical inbound ingress	shared secret + nonce/timestamp replay protection
POST	/v1/inbound/generic	Test ingest adapter	shared secret + nonce/timestamp replay protection

Policy Decision Envelope

{
  "decision": "allow | block | quarantine",
  "tier": "sandbox | limited | verified",
  "idempotency": {
    "key_regex": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$",
    "ttl_seconds": 259200
  },
  "checks": {
    "thread_has_inbound": true,
    "recipient_allowed": true,
    "suppression_match": false,
    "risk_score": 22,
    "grant_valid": false,
    "consent_valid": true
  },
  "reason": null
}

Canonical Hosts

{
  "web": "https://thrd.email",
  "api": "https://api.thrd.email"
}

Plan and Pricing Envelope

{
  "tier_1": {
    "free": { "eur_per_month": 0, "max_emails_per_month": 100 },
    "pro": { "eur_per_month": 9, "max_emails_per_month": 2000 }
  },
  "tier_2": { "eur_per_month": 29, "max_emails_per_month": 10000 },
  "tier_3": {
    "eur_per_month": 99,
    "max_emails_per_month": 50000,
    "custom_domain": true,
    "cold_outbound": true
  }
}