Technical

For developers and agent builders

The endpoints an agent calls, and how to run your own inbox.

Read the docs GitHub Deploy to Cloudflare Let your AI install it

For the plain version, read How it works.

What it is

One repository, two runtimes

The same TypeScript code runs on Cloudflare Workers and on Node. CI tests both.

  • Open source

    Six packages, the inbox app, an email gateway and this website. Decision records in docs/adr explain the design.

  • Run it where you like

    Workers with D1, queues and cron, or Node with one SQLite file. Each instance serves one business.

  • Licences

    AGPL-3.0-only for the server, the apps and the UI. MIT for the spec and the SDK, which verifies webhooks.

The doors

Three doors today, a web form next

All of this works today unless marked.

Read the API docs
Discovery
GET /.well-known/agent-inbox.json Names the instance, its item types, trust tiers and doors. Email is not listed.
REST
GET /openapi.json · /v1/* 55 operations: 11 public, 44 under /v1/owner. Built from the same schemas as the MCP tools.
MCP public
POST /mcp 11 tools for a customer's agent, no sign-in. acknowledge_receipt counter-signs a receipt.
MCP owner
POST /mcp/owner 34 tools for the owner and their AI. OAuth 2.1 with PKCE, or an owner API key.
Email in
POST /v1/email/inbound Raw MIME. Off until you set an inbound secret in Settings and send it in X-Inbox-Email-Secret. Emails become messages or replies, not bookings yet.
Web form
channel: form Being built For people with no agent. Reserved in the schema, not built yet.
Idempotency
Idempotency-Key · idempotency_key A repeated request with the same key gets the same answer: 200 with Idempotent-Replayed: true, never a second booking.
Access tokens
access_token · x-access-token Given to a caller with no key, so they can read, cancel or follow up on their item later.
Errors
application/problem+json A code, a message, and fields[{path, problem, message}] for each bad field.

Try it

Try the live instance

inbox.surfingdog.ai is our own instance. Its public doors need no key.

One call to start with

curl https://inbox.surfingdog.ai/v1/business

Returns the business name, domain, timezone, currency, languages and item types. No key needed, cached for five minutes.

Run it

Four ways to set it up

Same software each way.

  • Let your AI do it

    Give one line to Claude, Codex or Grok. It sets up the server, your subdomain and email in.

    Get the line

  • Cloudflare Workers

    One click on your own account. D1, R2 and a queue are created for you.

    Deploy to Cloudflare

  • Your own server

    Node 22.16, 24 or 26. Clone, install, build, run.

    Read the quickstart

  • Hosted by us

    We will run it for you, one database per business. Not open yet.

    Join the waitlist

Connect your AI

Let your own AI run the inbox

Claude, ChatGPT or any Streamable HTTP client can work the inbox for you.

How to connect

POST /mcp/owner

Each instance is its own OAuth server. Clients use OAuth 2.1 with PKCE and a Client ID Metadata Document, so nothing is registered by hand. Dynamic registration and owner API keys work too.

34 tools cover items, replies, the catalogue, opening hours, rules, webhooks and settings. Eight scopes, shown on the consent screen in plain words, limit what a client can do.

Contribute

Help build it

Read the decision records before you change the architecture.

  • The code

    Every change must pass the tests on Node and on workerd.

    Open the repository

  • How to work on it

    The toolchain and the rules of the repository.

    Read contributing

  • Ask for something

    Say what you need, and vote on what others have asked for.

    Feature requests

If you run a modified copy as a service, the AGPL requires you to make its source available. The spec and the SDK are MIT and carry no such duty.