Getting started
Run the communications service locally, list channels, and send one message.
Prerequisites
Follow Local development. Then:
./localenv up communications-api- API: localhost:8127
- Swagger UI: localhost:8127/api-docs
- Database:
postgres://postgres:postgres@localhost:5433/communications
Locally DEV_AUTH=1 trusts X-Dev-Principal as the caller. The service refuses to start with
that flag when APP_ENV is not local. The first request creates the person and, if the email
is in COMMUNICATIONS_PLATFORM_ADMINS, a platform-admin role. The default in
services/communications/process-compose.yaml is [email protected].
Empty Twilio or Mailgun keys leave those channels listed with available=false. WhatsApp and
Signal stay listed and unavailable.
Agent mailboxes are ${slug}@dev-ai.flow.life locally and in Azure dev, and
${slug}@ai.flow.life in prod. Create one Mailgun receiving route that
forwards that domain to /v1/webhooks/mailgun. The process does not create the
route. Locally MAILGUN_INBOUND_WEBHOOK_URL is usually empty.
List channels
curl -s localhost:8127/v1/channels \
-H "X-Dev-Principal: [email protected]" | jqTool catalog
curl -s localhost:8127/v1/tools \
-H "X-Dev-Principal: [email protected]" | jqsend_sms, send_email, send_announcement, list_conversations, get_conversation, and
get_message are the committed wrappers Foundry calls over HTTP.
Send one message
POST /v1/messages needs an Idempotency-Key. With no provider key the send is refused after
the row is queued, and the message is marked failed. Put real values in
services/communications/.env; name the keys only from
services/communications/.env.example.