Doorman docs

Quickstart #

With a coding agent: paste this, and answer its one question.

Add Doorman spam protection to this project's forms. Follow https://doorman.example/llms.txt. Ask me for the email that should receive real submissions.

By hand: about three minutes, no code beyond one attribute.

1. Sign up at /signup. You get a first form, an API key, and forwarding to your sign-up email. Add a sentence about your business (“We sell invoicing software to dental practices”) so Doorman knows what a real customer looks like for you.
2. Copy the form's action URL from the dashboard into your form:

   <form action="https://doorman.example/f/f_yourFormId" method="POST">

3. Done. Real submissions arrive where you pointed them (email, Slack or webhook). Pitches and bots land in the dashboard with the sentence that gave them away. Optionally add the snippet for timing and honeypot signals.

Agents & MCP #

Everything in these docs can be done without a browser, so a coding agent can set Doorman up end to end. There are two ways in:

• /llms.txt: the setup guide written for agents. It covers finding the project's forms, signing up, picking an integration, setting destinations and verifying with test submissions. Any agent that can run curl can follow it.
• /mcp: a remote MCP server (Streamable HTTP, JSON-RPC 2.0, plain JSON responses). Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.

A focused walkthrough for people is at Set up Doorman with your agent.

Install the MCP server

Claude Code:

claude mcp add --transport http doorman https://doorman.example/mcp

Once you have a key, you can add it to the connection so tools don't need it per call:

claude mcp add --transport http doorman https://doorman.example/mcp \
  --header "Authorization: Bearer $DOORMAN_KEY"

Codex (recent versions), in ~/.codex/config.toml:

[mcp_servers.doorman]
url = "https://doorman.example/mcp"

Cursor (recent versions), in .cursor/mcp.json:

{ "mcpServers": { "doorman": { "url": "https://doorman.example/mcp" } } }

Config formats for these clients change often; check your client's docs if one of these doesn't load. Without an Authorization header only doorman_docs and doorman_signup work; every other tool takes the key from the header or, failing that, an api_key argument. So an agent can sign up and keep going in the same session.

MCP tools

Every tool except doorman_docs and doorman_signup also accepts api_key. Tool errors come back as an MCP tool result with isError: true and a readable message.

Accounts made by agents

An agent signs up without a password. Doorman sets a random one and emails the owner a “set a password” link, valid for 7 days, to /app#/reset/<token>. Until then the account works fully through the API key. If the email already has an account, sign-up returns 409: create a key under Settings in the dashboard (/app#/settings) and give that to the agent instead.

Hosted forms #

CORS is open, so it works from any page. Doorman accepts application/x-www-form-urlencoded, multipart/form-data (file uploads are ignored) and JSON, up to 1 MB. A GET on the URL shows a short “this is a Doorman endpoint” page.

Field-name detection

Keep your field names. Doorman matches them case-insensitively; the first field that matches each role wins.

• No message field? The longest other field, if it's over 40 characters, is used as the message.
• Lengths are clipped: message 8,000 characters, email 320, name 200.
• Fields whose names start with _ are never stored as data. The ones below have a meaning.
• On a hosted form every other name is an ordinary field, including kind: the form's own kind always applies, so a bot can't choose which questions it's asked.

Special fields

What the visitor gets back

The response never reveals the verdict. A dropped bot and a real customer get the same thing:

• Plain form post: 303 redirect to _next, else the form's redirect URL, else https://doorman.example/thanks.
• JSON: if the request's Accept header contains json, or it sends any X-Requested-With header, the answer is 200 {"ok": true}.

Before judging, a request can be rejected outright: 404 for an unknown form id (JSON error), 413 over 1 MB.

Floods from one address

Past 30 submissions a minute from one IP to one form, Doorman still stores each one, but as hold with reason: "rate_limited": not judged, not counted as a check, and not forwarded. They wait in the dashboard's review queue, and labelling one real forwards it. Past a further 100 such submissions in an hour from that IP, they're no longer stored. The visitor gets the normal response either way, so an office behind one IP never sees an error.

The snippet #

Optional. Forms work without it; with it, Doorman sees how long the visitor spent on the page and whether JavaScript ran, which catches most scripts.

<script src="https://doorman.example/d.js" defer></script>

It finds every form whose action ends in /f/f_… (or that has data-doorman), including forms added later by a single-page app, and adds three hidden inputs: _t, _js and an off-screen _gotcha honeypot (tabindex="-1", aria-hidden, so keyboard and screen-reader users never meet it).

<form action="https://doorman.example/f/f_yourFormId" method="POST"
      data-doorman-ajax data-doorman-success="Got it. We reply within a day.">
  <label>Email <input name="email" type="email" required></label>
  <label>How can we help? <textarea name="message" required></textarea></label>
  <button type="submit">Send</button>
</form>
<script src="https://doorman.example/d.js" defer></script>

// building the request yourself
const body = { ...Object.fromEntries(new FormData(form)), ...window.Doorman.signals() };
await fetch(form.action, {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json" },
  body: JSON.stringify(body),
});
// always { "ok": true }

API reference #

Base URL https://doorman.example. JSON in, JSON out, request bodies up to 256 KB. CORS is open, but keep the key on your server.

Authentication

Send your API key as a bearer token. Keys look like dm_live_…. /v1/signup returns one; more live under Settings in the dashboard, where you can create several and revoke any of them.

Authorization: Bearer dm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create an account, its first form and an API key in one call. Made for agents and scripts; people can use /signup.

curl -X POST https://doorman.example/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@example.com",
    "site_url": "example.com",
    "site_context": "Example sells invoicing software to small businesses in the US.",
    "agent": "claude-code"
  }'

201 with api_key, account (as /v1/me), form (as /v1/forms, with action_url), dashboard_url, claim (a sentence saying where the password link went, or null), next_steps and note. 409 if the email already has an account; 429 after 5 sign-ups an hour from one IP.

Judge one submission and get a route back. Counts as one check.

Without form, the defaults apply: thresholds 0.8 / 0.2, enforce mode, no lists, nothing forwarded. The decision is still stored and shows up in your dashboard.

curl https://doorman.example/v1/check \
  -H "Authorization: Bearer $DOORMAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form": "f_yourFormId",
    "email": "sam@growthstudio.example",
    "name": "Sam",
    "message": "Love what you are building. We fill SaaS pipelines with done-for-you outreach. Open to a 15 minute chat?",
    "signals": { "ip": "203.0.113.7", "seconds_on_page": 38, "honeypot_filled": false }
  }'

Response:

{
  "id": "sub_8fKq2LmZ0aVb3c",
  "form": "f_yourFormId",
  "created_at": "2026-09-28T14:03:11.402Z",
  "route": "drop",
  "action": "drop",
  "p_real": 0.06,
  "reason": "pitch",
  "evidence": "We fill SaaS pipelines with done-for-you outreach.",
  "model": "jev-1.13.0",
  "latency_ms": 211,
  "label": null,
  "email": "sam@growthstudio.example"
}

In your handler: on drop, show the normal thank-you but don't save or notify; on hold, save it flagged for review; on deliver, the normal path. Never tell the visitor the verdict, and treat a Doorman timeout as hold, not drop (the SDK does this for you).

The account: id, email, plan (free, pro, business), plan_name, usage ({ month, checks, limit }), retention_days and plans (every plan's price and checks).

Forms

All forms, as { "data": [ … ] }, each with submissions (count) and last_at.

Create a form: one per distinct form on the site. Body: any of the settings below (name defaults to “Contact form”). Returns 201 with the form and next_steps. Up to 50 forms per account.

{ "name": "Demo request", "kind": "lead", "site_context": "Invoicing software for dental practices in the UK." }

Change any settings; omitted ones stay as they are.

curl -X PATCH https://doorman.example/v1/forms/f_yourFormId \
  -H "Authorization: Bearer $DOORMAN_KEY" -H "Content-Type: application/json" \
  -d '{ "slack_url": "https://hooks.slack.com/services/…", "mode": "watch", "allow_list": ["bigcustomer.com"] }'

Deletes the form. Its endpoint stops accepting posts (404).

Form settings

Read-only on the form object: id, action_url, webhook_secret, created_at. Responses include the webhook secret, so treat them like the key.

Test & test delivery

Judge a sample message with the form's settings, as if a person spent 40 seconds on the page. Free, not counted, not forwarded, and left out of submission listings. Body: { "message": "…", "email": "…" } (email optional). Returns the same object as /v1/check.

POST /v1/forms/f_…/test  { "message": "Hi, we run a 12-person dental clinic and spend a day a week chasing invoices. Can we see a demo?" }   -> deliver
POST /v1/forms/f_…/test  { "message": "We help SaaS founders fill their pipeline with done-for-you outreach. 15 min chat?" }                 -> drop

Sends a sample submission to every destination the form has and returns { "log": [ { "to": "webhook"|"slack"|"email", "ok": true, "status": 200, "ms": 143 } ] }, with error on failures.

Ready-to-paste integration code for a form: { "platform", "note", "code" }. Platforms: html, ajax, react, nextjs, express, curl, webflow, framer, wordpress. Unknown platform: 422.

Submissions

Recent decisions, newest first, as { "data": [ … ], "next_before": "…" } with the same objects as /v1/check. Test submissions are excluded.

curl "https://doorman.example/v1/submissions?review=true&limit=20" \
  -H "Authorization: Bearer $DOORMAN_KEY"

One submission. 404 if it doesn't exist or isn't yours.

Tell Doorman what a submission really was. Body: { "label": "real" } or { "label": "spam" }. Returns the updated submission.

• real sets action to deliver. If it was never forwarded and it came from a hosted form (or an API check with forward: true) whose form has destinations, it's forwarded now as submission.delivered. This is the “rescue” button in the dashboard.
• spam sets action to drop and cancels any pending delivery retries. Nothing already sent is recalled.

Errors & limits

Errors are JSON with a human-readable message: { "error": "…" }.

A model error is not an HTTP error: you get 200 with route: "hold" and reason: "doorman_error". Hosted forms never return 429; see floods.

Routes & thresholds #

Doorman's models answer typed questions about each submission: real (a probability), pitch, automated (and fraud for checkouts), and evidence, a choice among the message's own sentences. Only real decides the route, using thresholds that live in Doorman, per form:

The reason on a hold or drop is whichever of pitch, automated or fraud scored highest, if it scored at least 0.5; otherwise null.

Set them equal to remove the hold lane; lower drop_below to drop only the obvious.

Kinds #

A form's kind changes what “genuine” means and what Doorman looks for. For sign-ups without a message, the evidence is the field that gave it away, such as Email: ….

Checkout signals

For checkout, send the check from your server with what your payment flow knows in signals, plus order. Missing values are fine. The evidence is one of these facts, e.g. "Payment attempts before success: 6".

{
  "kind": "checkout",
  "email": "buyer@example.com",
  "order": { "items": "10× $50 gift card", "total_usd": 500 },
  "signals": {
    "card_country": "US", "ip_country": "RO",
    "attempts": 6, "device_orders_last_hour": 4,
    "account_age_days": 0, "name_match": false, "card_type": "prepaid"
  }
}

Allow & block lists #

Each form has an allow_list (always delivered) and a block_list (always dropped). A matching submission isn't judged and doesn't use a check; its reason is allow_list or block_list and p_real is null. The allow list is checked first.

Matching is on the sender email Doorman detected and is case-insensitive. Lists apply to hosted posts, /v1/check calls with a form, and tests.

Webhooks #

Set a webhook URL on a form and Doorman POSTs JSON to it for every submission it forwards. Two events:

• submission.delivered: a deliver, a watch-mode drop, or a rescue.
• submission.held: a hold, sent with held: true (only if the form forwards holds).

Drops never reach your webhook unless you rescue them.

POST /your/webhook
Content-Type: application/json
User-Agent: Doorman-Webhook/1
Doorman-Signature: t=1790604191,v1=5f2c0a…e41b

{
  "event": "submission.held",
  "id": "sub_8fKq2LmZ0aVb3c",
  "created_at": "2026-09-28T14:03:11.402Z",
  "form": { "id": "f_yourFormId", "name": "Contact form" },
  "route": "hold",
  "held": true,
  "p_real": 0.46,
  "reason": null,
  "evidence": "Could I resell this to my own clients?",
  "submission": {
    "email": "ana@studio.example",
    "name": "Ana",
    "message": "Hi! Could I resell this to my own clients? We manage books for about 30 small shops.",
    "fields": { "company": "Studio Ana" }
  },
  "dashboard_url": "https://doorman.example/app#/inbox/sub_8fKq2LmZ0aVb3c"
}

Retries

Each attempt has an 8-second timeout; any 2xx counts as delivered. If a destination fails (webhook, Slack or email), only that destination is retried, after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours: six attempts in all. The log of every attempt is on the submission in the dashboard. Labelling a submission spam cancels its pending retries. Make your handler idempotent on id, since a retry can arrive after a slow success.

Verifying the signature

Each form has its own secret (webhook_secret, whsec_…, on the form object; rotate it in the dashboard). The header is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 with your secret over "<t>.<raw body>". Verify against the raw request body, compare in constant time, and reject timestamps more than 5 minutes old.

With the SDK, verifyWebhook resolves to the parsed payload and rejects if anything is wrong:

import express from "express";
import { verifyWebhook } from "doorman-client";

// keep the body raw on this route
app.post("/hooks/doorman", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = await verifyWebhook(req.body, req.get("Doorman-Signature"), process.env.DOORMAN_WEBHOOK_SECRET);
  } catch {
    return res.sendStatus(401);
  }
  if (event.held) { /* flag it for a human */ }
  // event.submission.email, event.submission.message, event.evidence …
  res.sendStatus(200);
});

Without the SDK, it's a few lines:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyDoorman(rawBody, header, secret) {
  const m = /t=(\d+),v1=([a-f0-9]+)/.exec(header || "");
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) throw new Error("bad or old signature");
  const expected = createHmac("sha256", secret).update(`${m[1]}.${rawBody}`).digest();
  const got = Buffer.from(m[2], "hex");
  if (got.length !== expected.length || !timingSafeEqual(got, expected)) throw new Error("signature mismatch");
  return JSON.parse(String(rawBody));
}

Slack & email #

Forwarding goes to every destination a form has, in parallel, with the same rules and retries as webhooks.

• Slack: paste a Slack incoming webhook URL. Each message shows the sender, the message quoted, and an “Open in Doorman” link. Held ones are marked with P(real) and why.
• Email: one or more addresses. New accounts forward to the sign-up address by default. Reply-To is set to the sender, so you can just hit reply. Held ones have a [Held] subject prefix and a banner with the evidence.

On a self-hosted server, email needs RESEND_API_KEY (see Self-hosting); without it, email attempts are logged as not configured (and not retried) while webhook and Slack still work.

Watch mode #

Set a form's mode to watch to try Doorman on real traffic without risk. Everything is judged and stored exactly as in enforce mode, but anything that would have been dropped is forwarded as a normal submission.delivered. Its route still says drop and its action says deliver, so you can see in the dashboard and the API what Doorman would have done.

Holds behave as usual in watch mode. When the drops look right, switch to enforce.

Plans, retention & failure #

A check is one judged submission, from a hosted form or /v1/check. Tests, list matches and flood-limited submissions don't count. Months are calendar months in UTC. You get an email at 80% and 100%. Submissions older than your plan's retention are deleted automatically.

Doorman fails open, into the hold lane, never into drop:

If forwarding holds is turned off on a form, held submissions still wait in the dashboard's review queue; they just aren't pushed to you.

Limits

Live service status and 90-day uptime: /status (JSON at /status.json).

Passwords & your data #

• Set a password for an agent-made account from the link in the welcome email (valid 7 days).
• Forgot it? Use /app#/forgot. Reset links are valid for an hour, and using one signs out every other session.
• API keys are shown once when created, stored only as hashes, and can be revoked in Settings.
• Export everything Doorman holds about your account as JSON, or delete the account and all its submissions, from Settings.

Submissions are sent to our machine-learning provider only to be judged and aren't used for training. See the privacy policy.

Node SDK #

doorman-client is a zero-dependency wrapper for Node 20+, Bun, Deno, Cloudflare Workers and edge runtimes, with TypeScript types.

npm install doorman-client

import { Doorman, verifyWebhook } from "doorman-client";

const doorman = new Doorman(process.env.DOORMAN_KEY, {
  baseUrl: "https://doorman.example",
});

// same body and response as POST /v1/check; never throws on an outage
const r = await doorman.check({ form: "f_yourFormId", email, name, message });
if (r.action !== "drop") await saveLead({ email, message, held: r.action === "hold" });
return res.json({ ok: true }); // same answer for everyone

// a person said it was real after all
await doorman.label(r.id, "real");

Act on r.action rather than r.route: it respects watch mode and labels.

Self-hosting #

Doorman is one Node process and one SQLite file, with zero npm dependencies, MIT licensed. It needs Node 22.13 or newer (for the built-in node:sqlite).

cp .env.example .env    # everything is optional for local dev
npm start               # → Doorman on http://localhost:3000
npm test

With no TypeSafe key, judging runs in mock mode: cheap heuristics with the same response shape, and a mock model name on every decision so nobody mistakes it for the real thing. GET /health reports the mode. A maintenance loop runs every minute for delivery retries and retention.

Real environment variables win over .env.

Docker

There are no dependencies to install, so a Dockerfile is four lines:

FROM node:22-alpine
WORKDIR /app
COPY . .
CMD ["node", "server.js"]

Add .env, data/ and .git to a .dockerignore so secrets and your local database stay out of the image.

docker build -t doorman .
docker run -p 3000:3000 -v doorman-data:/data \
  -e DATABASE_PATH=/data/doorman.db \
  -e BASE_URL=https://forms.yourdomain.com \
  -e TYPESAFE_API_KEY=… \
  doorman

Behind a proxy, Doorman reads the client IP from CF-Connecting-IP, Fly-Client-IP or X-Forwarded-For, and the country from CF-IPCountry.