Communications Service

Shared send-and-thread pipe for SMS and email. Foundry and a later announcements product call the same API.

Communications is the service that sends SMS and email, receives provider webhooks, and groups replies into 1:1 threads. Twilio and Mailgun keys stay here. Mail to ${slug}@ai.flow.life (prod) or ${slug}@dev-ai.flow.life (dev) lands here and wakes the Foundry agent with that slug. Foundry does not hold comms keys.

Domain: Services
Kind: Go HTTP service
Lifecycle: Active
flowctl project: None
Stacks: Runs on its own
Source: services/communications

Run it locally

Port 8127, Dev Auth, listing channels, and sending one message.

Architecture

Conversation and announcement domains, adapters, and the Foundry wake.

API

Send, list, bulk, webhooks, and the tool catalog.

Operations

Local port, provider keys, and why it is not deployed yet.

Two domains, one database

conversation is a 1:1 thread. announcement is one blast to many recipients. Replies to a blast land on the 1:1 thread. The join is conversation_message.announcement_id, so both domains share one sqlc package.

Diagram. Text representation: flowchart LR Caller[Foundry or announcements] Send["POST /v1/messages"] Bulk["POST /v1/announcements"] Twilio[Twilio] Mailgun[Mailgun] Thread[(conversation)] Foundry[foundry-api] Caller --> Send --> Twilio Caller --> Send --> Mailgun Caller --> Bulk --> Twilio Caller --> Bulk --> Mailgun Twilio -->|"webhook"| Thread Mailgun -->|"webhook"| Thread Thread -->|"POST wake ids only"| Foundry

Diagram source

flowchart LR
  Caller[Foundry or announcements]
  Send["POST /v1/messages"]
  Bulk["POST /v1/announcements"]
  Twilio[Twilio]
  Mailgun[Mailgun]
  Thread[(conversation)]
  Foundry[foundry-api]

  Caller --> Send --> Twilio
  Caller --> Send --> Mailgun
  Caller --> Bulk --> Twilio
  Caller --> Bulk --> Mailgun
  Twilio -->|"webhook"| Thread
  Mailgun -->|"webhook"| Thread
  Thread -->|"POST wake ids only"| Foundry

What it owns

Threads and messages, including provider_message_id
Bulk announcements and per-recipient status
Twilio SMS and Mailgun email adapters
The committed tool catalog Foundry wraps as harness tools
The optional agent_id on a thread that decides who to wake

What it does not own

LLM keys (broker). Agent processes (foundry). Workspace conversations are a different database.

See ADR 0045.

Canonical service README: services/communications/README.md.