Documentation

Product overview

What TextTree ships today in alpha: Phoenix-native auth, suppression-gated messaging, verified webhooks, and controlled MCP execution.

Product overview

TextTree is an outbound messaging control plane for agentic and developer-facing products.

The public site runs in Astro. The authenticated app, JSON API, webhooks, and MCP endpoints run in Phoenix. Neon-backed Ecto data and Oban workers hold the operational state.

What exists today

The current alpha includes six concrete surfaces:

  • a public Astro site for product pages, docs, and blog content
  • an authenticated Phoenix operator console at /app
  • public JSON account bootstrap for username/password AI agents
  • a developer API for queuing and reading outbound messages
  • verified webhook ingestion for messaging and funding providers
  • MCP tool listing and execution with scopes, quotas, timeouts, and audit records
  • guided SMS workflows for quick dashboard sends, dedicated sender management, campaign setup, contact import, and message inspection

Operator workflow

TextTree is usable today through either a browser account or a headless agent account:

  1. Register or log in through TextTree, or create a headless account through POST /api/v1/accounts or POST /mcp/accounts.
  2. Use a TextTree access token with the required API or MCP scopes.
  3. Confirm the recipient is not under a workspace or campaign suppression.
  4. Set a spend limit in /app.
  5. Optionally create a Peer funding session in /app.
  6. Send messages through POST /api/v1/messages, the Send page, dashboard quick-send, or a campaign sequence.
  7. Track message state through GET /api/v1/messages/:id and provider events in /app.

Current guardrails

  • Phoenix-native auth identities are normalized into local TextTree users.
  • Headless account bootstrap returns backup codes and a scoped bearer token, and is limited to one successful account creation per IP every five minutes.
  • Outbound SMS does not require a global granted consent record.
  • Workspace suppressions block all outbound sends to that phone number.
  • Campaign suppressions block only that campaign’s rendered deliveries.
  • Provider STOP/opt-out webhooks create or update workspace suppressions before future sends.
  • Spend is authorized before a provider call is enqueued.
  • Dashboard quick-send, the Send page, API sends, and campaign sends share the same outbound safety path.
  • Connected branded numbers can be selected for one-off sends. If a selected sender is disconnected or does not belong to the workspace, dispatch fails before provider execution instead of silently falling back.
  • Provider webhooks are verified, normalized, deduplicated, and replayable.
  • MCP execution is constrained by TextTree token scopes, server allowlists, quotas, and timeout policy.
  • Affiliate public offer, hub, and redirect routes are disabled unless the public_routes affiliate feature flag is enabled for that environment.

Current alpha constraints

The docs in this site describe the implemented alpha, not the eventual product surface.

  • Workspace/campaign suppression management and spend limits are operator workflows in /app, not public JSON endpoints.
  • Messaging is adapter-driven and stays behind a provider boundary.
  • Funding is optional and currently lives behind the Peer provider boundary.
  • MCP tools are configured server-side; there is no public tool-registry editor yet.
  • Campaign setup supports snippets, contact lists, CSV import, sequences, and suppressions inside /app; there is no public campaign JSON API yet.
  • Repo-local ADRs define the current implementation baseline while canonical spec import work remains open.