Reverbin

Communication infrastructure for autonomous agents.

Reverbin gives agents real email inboxes, threaded conversations, signed webhooks, delivery logs, policy guardrails, and an operator dashboard on production email rails.

• Live site: https://reverbin.com
• API base URL: https://api.reverbin.com
• API reference: docs/API.md
• Human quickstart: docs/QUICKSTART.md
• Agent integration guide: docs/AGENTS.md
• Agent-readable index: llms.txt
• Downloadable agent skill: SKILL.md
• Create free inbox: https://reverbin.com/signup

What Reverbin is for

Agents often need to touch normal human workflows: support, onboarding, billing, vendor follow-up, verification, and escalation. Those workflows still happen over email.

Reverbin gives each agent an addressable inbox and gives the application a small control plane around it:

1. Create a free inbox at https://reverbin.com/signup and copy the one-time quickstart block.
2. Store REVERBIN_API_KEY, REVERBIN_INBOX_ID, and REVERBIN_INBOX_EMAIL in the agent secret store.
3. Send mail to the created inbox.
4. Fetch thread context.
5. Let the agent reply through policy-controlled API calls.
6. Keep delivery logs, audit rows, and policy decisions for humans.

Current capabilities

• Fastify TypeScript API.
• Public Reverbin landing page.
• App-token protected operational dashboard at /dashboard.
• Postgres-backed inboxes, threads, messages, policies, webhooks, delivery logs, approvals, and audit logs.
• Redis/BullMQ worker for queued webhook delivery.
• Resend inbound/outbound provider integration.
• Mock provider for local development.
• TypeScript client exported as ReverbinClient.
• Frictionless default replies with risk flags retained for audit.
• Optional approval policies for higher-risk workflows.

Five-minute agent flow

Start by creating the first inbox and API key:

https://reverbin.com/signup

For agent runtimes that support downloadable procedures, import SKILL.md.

Then use the SDK with the values returned from signup:

import { ReverbinClient } from '@builtbyecho/reverbin';

const reverbin = new ReverbinClient({
  baseUrl: process.env.REVERBIN_BASE_URL ?? 'https://api.reverbin.com',
  apiKey: process.env.REVERBIN_API_KEY,
});

const inbox = await reverbin.inboxes.create({
  email_address: 'user@reverbin.com',
  display_name: 'Support Agent',
});

await reverbin.webhooks.create({
  url: 'https://agent.example.com/reverbin/webhook',
  events: ['email.received', 'email.sent'],
  secret: process.env.REVERBIN_WEBHOOK_SECRET,
});

After inbound email arrives, fetch the thread and reply:

const thread = await reverbin.threads.get('thr_123');

await reverbin.threads.reply(thread.id, {
  text: 'Thanks — I can help with that.',
});

API shape

All public API routes require bearer auth:

Authorization: Bearer $REVERBIN_API_KEY

Core routes:

POST /v1/agent-signups
POST /v1/inboxes
GET  /v1/inboxes
GET  /v1/inboxes/:id
GET  /v1/inboxes/:id/threads
GET  /v1/threads/:id
POST /v1/threads/:id/reply
POST /v1/webhooks
GET  /v1/webhooks
GET  /v1/webhook-deliveries
GET  /v1/audit-logs

See docs/API.md for request/response examples.

Local development

cp .env.example .env
npm install
npm run migrate
npm run dev

Health check:

curl http://127.0.0.1:8797/health

Run tests:

npm run check

Vercel frontend deploy

The backend/API/dashboard stays on the VPS at https://api.reverbin.com. The Vercel deployment is a static frontend export for the public lander, docs redirect, favicon, and llms.txt.

When importing this repo into Vercel from GitHub, use:

Framework preset: Other
Build command: npm run build:frontend
Output directory: leave blank / default
Install command: npm install

Do not set Output Directory to vercel-static or any other folder in Project Settings. If a previous failed attempt saved vercel-static, clear that field under Vercel → Project → Settings → Build & Development Settings. vercel.json encodes the build command. The build emits Vercel's native Build Output API directory at .vercel/output/static; Vercel discovers that directory automatically when Output Directory is blank. Backend paths such as /dashboard, /v1/*, /health, and /readyz redirect to https://api.reverbin.com.

To verify locally:

npm run build:frontend

Dashboard access

The operational dashboard is app-token protected.

• Browser login: GET /dashboard/login, then enter DASHBOARD_TOKEN or use the signup email code flow.
• Scripted/operator access: Authorization: Bearer $DASHBOARD_TOKEN on GET /dashboard.
• If DASHBOARD_TOKEN is unset, dashboard auth falls back to the API key env var used by the server.

Webhook signing

Agent webhooks are signed with HMAC-SHA256.

The signature header is:

x-echo-email-signature: sha256=<hmac_hex_digest>

The HMAC input is the raw JSON request body. The secret is the secret value supplied when creating the webhook endpoint.

Production deploy shape

The live runtime currently keeps the original service path/name for continuity:

/opt/agent-email-layer
/etc/agent-email-layer/env
/var/lib/agent-email-layer/raw-mime
/var/lib/agent-email-layer/attachments

Services:

agent-email-layer.service
agent-email-layer-webhook-worker.service

Default listener is 127.0.0.1:8797 behind Caddy.

Safety defaults

• No raw secrets in repo/docs.
• API keys should live in environment variables or an agent secret store.
• Default policy allows normal replies immediately but records risk flags.
• Approval workflows are opt-in policy constraints, not the default UX.
• Webhook endpoint secrets are stored server-side and never returned by list routes.
• Delivery logs and audit logs are first-class operational surfaces.