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.Available after a provisional inbox is claimed and activated. Clients must treat the inbox as provisional until that lifecycle completes.

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"]
}

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"
  }
}

Gate Controlled Beta

Do not assume Gate availability from the presence of its schemas. Check the API response and tenant feature state. Existing inbox, polling, ACK, reply and send contracts remain independent.

{
  "availability": "controlled_beta",
  "authority_chain": [
    "evidence",
    "deterministic_policy",
    "single_use_capability",
    "credential_bound_execution",
    "replayable_receipt"
  ],
  "rule": "LLMs may interpret; only deterministic policy authorizes",
  "discovery": "OpenAPI.paths./v1/actions/authorize"
}

Endpoint Matrix

Method	Path	Intent	Constraints
GET	/v1/activation	Run the guided first-email test	returns milestone timestamps, next_action and precise provider-agnostic delivery errors
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
POST	/v1/actions/authorize	Evaluate one exact consequential action	controlled beta; deterministic policy returns allow\|review\|deny and binds the canonical action hash
GET	/v1/approvals/:id	Resume a human-reviewed action	controlled beta; authenticated tenant and agent scope; human responses never contain capability bearer material
POST	/v1/capabilities/redeem	Redeem single-use execution authority	controlled beta; exact action, executor, target, environment, TTL and revocation are verified
GET	/v1/action-receipts/:id	Read redacted replayable authority receipt	controlled beta; tenant-bound hash chain; no capability bearer or raw evidence exposure
GET	/v1/outbound/:request_id	Check async outbound status	returns pending\|processing\|sent\|failed plus stable delivery_error code and retryability
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 paid-plan checkout link	agent-auth; paid limits are outbound recipient units; payment capacity never bypasses recipient authority, policy or suppressions
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 usage windows and entitlement state	agent-auth; inbound is observational and unmetered; outbound is recipient-unit based with daily/monthly windows
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
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

{
  "inbound_billing_mode": "unmetered",
  "incoming_monthly_message_quota": null,
  "fair_use_qualification": "No monthly incoming-message quota. Fair-use, anti-abuse, 5 MB message-size and retention limits apply.",
  "unit": "outbound_recipient",
  "plans": {
    "free": {
      "eur_per_month": 0,
      "payment_card_required": false,
      "outbound_recipient_units_monthly": 25,
      "outbound_recipient_units_daily": 5,
      "authority": "reply_only_latest_verified_inbound_sender"
    },
    "starter": {
      "eur_per_month": 9,
      "outbound_recipient_units_monthly": 2000,
      "authority": "tier_1_reply_only"
    },
    "limited": {
      "eur_per_month": 29,
      "outbound_recipient_units_monthly": 10000,
      "authority": "tier_2_existing_recipient_authority"
    },
    "verified": {
      "eur_per_month": 99,
      "outbound_recipient_units_monthly": 50000,
      "authority": "tier_3_verified_controls",
      "custom_domain": true
    }
  }
}