Family Drill
Install the bot

Run Family Drill from one conversation.

The organizer installs the bot, verifies once, and adds family emails. Family members do not set anything up. They receive surprise practice emails, get instant coaching when they click, and the organizer sees what landed in the bot.

Template not published

Choose your app

Hosted: use Family Drill on familydrill.com. Self-hosted: clone the app, run it on your own domain with your own email service provider, and give that app URL to the bot.

Install and authentication

There is no public bot-template link yet. When it is published, the install button will appear here. We will not send you to a placeholder or invented URL.

After the organizer signs in by magic link, call POST /api/bot/install/start in that authenticated browser session. The endpoint uses the verified session identity, not a submitted email, and returns installId and a database-backed botToken.

Send Authorization: Bearer <bot_token> or X-Family-Drill-Token: <bot_token>. This token is not an ESP key. Requests with a bad token receive 401; sends and roster writes are rejected while the install is inactive or the household is paused.

Endpoints

POST /api/bot/install/start

Use the verified organizer session to issue an install ID plus bot token.

GET /api/bot/install

Read install state, capabilities, organizer email, and pause state.

GET · POST /api/bot/members

List the bot-owned roster or add a member with name and email.

PATCH · DELETE /api/bot/members/:id

Update or remove a roster member.

POST /api/bot/drills

Queue a fictional drill and mint a reveal path on this app.

GET /api/bot/events?since=<cursor>

Poll sent, revealed, engaged, and failed events.

GET /api/bot/drills/:id

Read lesson bullets and the deliberate-button engagement method.

POST /api/bot/pause · /api/bot/resume

Stop or resume all household sends and minting.

GET /api/bot/health

Read service, install, and household pause state.

Queue a drill

Send {"memberId":"maya","scenarioId":"surprise","sendAt":"2026-09-11T14:00:00Z"}. All fields are optional: the app can select a member and fictional scenario. The response contains drillId, memberId, scenarioLabel, revealPath, and scheduledFor. The stub shifts requests out of its 21:00–08:00 UTC quiet hours and limits a household to five drills per hour.

Events and coaching

Event polling returns an array of { type, at, drillId, memberName, summary, cursor }. Types are drill.sent, drill.revealed, lure.engaged, and drill.failed. Pass the last cursor back as since. Drill detail returns only coaching context and lesson bullets. It never returns credentials. A lure engagement is recorded only when the member deliberately presses the reveal-page button.

Safety boundaries

  • Use fictional organizations only. Never spoof a real brand or From identity.
  • Email lures can appear to request personal information, but their links must open the reveal, not a data-entry form.
  • Never collect passwords, Social Security numbers, card details, or other secrets.
  • Never put ESP keys in bot instructions, actions, chat, or templates. Delivery stays in the app.
  • Only the organizer completes setup; there is no per-relative setup workflow.

No bot template or public install URL has been published.