For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Interest signup

What it does

Applications are agent-only. Submission starts email confirmation¹¹. A person must follow the email link in a browser to confirm signup. Confirmation does not reserve a seat.¶

An agent applies for a person through the joinInterest capability. A capability is one named action with shared value definitions and a server-side implementation. Call it through MCP, POST /api/joinInterest, or the command-line interface (CLI). MCP²⁷ means Model Context Protocol, which lets an agent discover and call tools.¶

The agent view of /tokenmaxx carries a fresh page ticket and the application steps. Ask the questions, show an editable card, and submit only what the person approves. Refusals return the same answer as success, and the person still confirms by email.¶

SubscriberIntake and SubscriberConfirm are ports in core: interfaces for starting email confirmation and confirming a signup. packages/subscriber-delivery provides the adapter, the implementation that connects those interfaces to external delivery. The Worker chooses and supplies that implementation when it starts.¶

See hexagonal architecture¹⁹. List signup is separate from account authentication¹⁶.¶

The standard

• A person must confirm their email before joining.¶
• Consent is explicit: the person approves the agent’s exact card and contact permission. An agent must not infer permission to subscribe someone from their address or an unrelated request.¶
• Agent application refusals receive a neutral answer rather than revealing whether an address is on file. Expired confirmation links have deliberate refusal responses. Retired submission endpoints return 410 without capturing or delivering an application.¶
• Provider details remain outside core; no-core-adapters enforces that boundary.¶
• An agent application needs a fresh page ticket, contact consent, and the person’s approval of the exact application data. A ticket works once.¶

Applicant identity

joinInterest accepts optional name and x fields. The name trims whitespace and allows 1–100 characters. This keeps preferred names short. Skipped fields and historical applications omit both keys.¶

• The X field accepts a handle or profile URL and stores https://x.com/handle in lowercase. Handles allow 1–15 ASCII letters, digits or underscores, including existing short handles. It refuses status, intent and navigation URLs.¶
• X documents the 15-character limit and the allowed characters. Its current account-renaming guidance requires more than four characters. This field reads existing profiles rather than registering usernames.¶
• Identity is stored in protected form in the application’s started event, which records the start of an application. It uses the same contact key as the answers. Erasure removes that key and its rows.¶
• Only the authenticated application reader reads the protected identity. The delivery request is unchanged and carries neither field.¶
• Capability observers receive identity fields with their values removed. Request analytics¹⁸, trace spans, and logs never receive those values. A trace span records an operation’s timing and outcome.¶
• MCP request tracing is disabled in the protocol implementation for modern and legacy protocols. The protocol’s tools/call span records raw parameters before the capability observer can remove sensitive values.¶

Operator commands

Set INTEREST_OPERATOR_TOKEN through the local environment schema. Keep its value private.¶

• rat-stack intake list --submission-id <id> reads one application.¶
• rat-stack intake erase --submission-id <id> erases local contact data and sealed answers.¶
• rat-stack intake redeliver --submission-id <id> retries a ready application with its original submission ID.¶

Repeat --submission-id to provide an ordered batch. Redelivery processes one ID at a time.¶

• Only ready contacts without an abuse hold can be sent by default. Erased contacts appear as missing.¶
• Add --dry-run to inspect every named ID without sending or changing state. Eligible rows say would_send.¶
• Add --include-refused only for explicitly approved IDs whose refusal came from a verified availability failure. This per-call option repairs named refused contacts to ready before delivery. It never permits held or accepted contacts.¶
• The live batch stops at the first skipped, refused, or retry outcome. The result lists IDs not attempted.¶
• Each row contains the pre-run state in previousState and the resulting state.¶
• The response contains submission IDs, outcomes, and states. It contains no email addresses or answers.¶

The operator route is POST /operator/interest/applications/redeliver. It uses the same bearer token as erasure.¶

If the command fails, read application states before retrying. A failed request can have completed part of the batch.¶

A scorer outage alone saves a ready contact without sending. The response tells the person that confirmation is delayed.¶

Non-holding signals can accompany that outage: ticket_instant, no_answers, jev_off, and jev_clear. Real abuse holds and unknown signals keep the contact held, even with a scorer outage.¶

Use redelivery after the outage is fixed. The saved submission ID stays unchanged.¶

Rate refusals return a busy message and save nothing. The agent waits one minute and retries once.¶

How to check

• Read apps/site/src/interest/routes.ts for email confirmation, retired-routes.ts for 410 responses, and packages/core/src/join-intake.ts for agent applications. The only published signup capability is joinInterest.¶
• Run pnpm --filter @rat-stack/core test for lifecycle behavior and pnpm --filter @rat-stack/site test for submission and confirmation integration tests. pnpm --filter @rat-stack/subscriber-delivery test checks the adapter contract.¶
• With an authorized test address, approve an agent application, receive the confirmation email, follow its link, and confirm. Source and local tests alone do not prove inbox delivery or the external list state.¶
• Check OpenAPI for joinInterest and read the agent view of /tokenmaxx for the application steps. Do not bypass confirmation.¶

Last changed 2026-10-12 in 8fa3c6d. Source on GitHub. Change log.