Skip to content

Communications Service

The Communications Service provides email, SMS, and voice call capabilities for your Aegis Stack application using industry-leading providers.

Raven delivering message

Start Sending Messages in Minutes

Generate a project with comms service and start communicating:

aegis init my-app --services comms
cd my-app
uv sync && source .venv/bin/activate
my-app comms status

Free tiers available for both providers - no credit card required to get started!

What You Get

  • Email via Resend - Modern email API with excellent deliverability
  • SMS via Twilio - Worldwide SMS messaging with delivery tracking
  • Voice Calls via Twilio - Outbound calls with TwiML control
  • CLI Interface - Send messages directly from command line
  • REST API - Complete /comms/* endpoints for integration
  • Health Monitoring - Service health checks and configuration validation

Architecture

graph TB
    subgraph "Communications Service"
        CommsService["📧 Comms Service<br/>Email, SMS, Voice"]

        CLI["💻 CLI Interface<br/>comms email, sms, call"]
        API["🌐 REST API<br/>/comms/email, /comms/sms, /comms/call"]

        subgraph "Providers"
            Resend["📨 Resend<br/>Email API"]
            Twilio["📱 Twilio<br/>SMS & Voice"]
        end
    end

    Backend["⚡ Backend Component<br/>FastAPI"]

    subgraph "Worker Component"
        ArqQueues["📋 arq Queues<br/>Background Jobs"]
        Redis[("🔴 Redis<br/>Queue Storage")]
    end

    CommsService --> CLI
    CommsService --> API
    CommsService --> Resend
    CommsService --> Twilio
    API --> Backend
    CommsService -.->|async jobs| ArqQueues
    ArqQueues --> Redis

Quick Start

1. Generate Project with Comms Service

aegis init my-app --services comms
cd my-app
uv sync && source .venv/bin/activate

2. Configure Providers

Set up your environment variables:

# Email (Resend) - Get key at resend.com/api-keys
export RESEND_API_KEY=re_xxxxxxxxxxxx
export RESEND_FROM_EMAIL=onboarding@resend.dev  # Use your domain in production

# SMS/Voice (Twilio) - Get credentials at console.twilio.com
export TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export TWILIO_PHONE_NUMBER=+15551234567

3. Check Configuration

my-app comms status

4. Send Your First Message

# Send an email
my-app comms email send 'your@email.com' --subject 'Hello from Aegis Stack' --text 'Your first message!'

# Send an SMS (trial accounts: verified numbers only)
my-app comms sms send '+1YOUR_NUMBER' 'Hello from Aegis Stack!'

Provider Free Tiers

Provider Free Tier Limits
Resend 100 emails/day 3,000/month, no credit card
Twilio $15 trial credit ~1,900 SMS or ~1,765 call minutes

Musings: On SMS Registration (November 25th, 2025)

It's been more annoying than I thought to get a toll-free number, or any number for that matter. Voice calls work fine, but I need to jump through more hoops than I anticipated for text messaging. Which makes this less "just works" than I would like. It also looks to be a systemic issue that I'll run into with other providers...

Configuration

Email (Resend)

# .env
RESEND_API_KEY=re_xxxxxxxxxxxx
RESEND_FROM_EMAIL=noreply@yourdomain.com

SMS/Voice (Twilio)

# .env
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_PHONE_NUMBER=+15551234567

With the secrets component, these can be set in the Overseer instead, while the app runs. The from address offers the Resend account's verified domains and is checked against them; the from number and messaging service offer the Twilio account's own.

Sending domains

Resend sends only from a verified domain. The Email section of Overseer > Comms, and the Flet dashboard's Email tab, list the account's domains with their status:

  • Check asks Resend to look at the domain's DNS now.
  • Add domain registers a new one and shows the DNS records to create at your registrar; Check once they are in place.

A send-only Resend key cannot list domains; the section says so, and sending still works.

Usage Examples

CLI

# Check service status
my-app comms status

# Send email
my-app comms email send 'user@example.com' --subject 'Welcome' --text 'Welcome to our service!'

# Send SMS
my-app comms sms send '+15559876543' 'Your code: 123456'

# Make voice call (uses demo TwiML by default)
my-app comms call make '+15559876543'

API

# Start server
make serve

# Send email via API
curl -X POST http://localhost:8000/api/v1/comms/email/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["user@example.com"],
    "subject": "Welcome",
    "text": "Hello from the API!"
  }'

# Send SMS via API
curl -X POST http://localhost:8000/api/v1/comms/sms/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15559876543",
    "body": "Your verification code is 123456"
  }'

Python

from app.services.comms.service import (
    make_call_simple,
    send_email_simple,
    send_sms_simple,
)

# Send email
result = await send_email_simple(
    to="user@example.com",
    subject="Welcome",
    text="Hello, welcome to our service!"
)
print(f"Email sent: {result.id}")

# Send SMS
result = await send_sms_simple(
    to="+15559876543",
    body="Your verification code is 123456"
)
print(f"SMS sent: {result.sid}")

# Make call
result = await make_call_simple(
    to="+15559876543",
    twiml_url="https://example.com/twiml"
)
print(f"Call initiated: {result.sid}")

Next Steps

Topic Description
Provider Setup Detailed Resend and Twilio account setup
API Reference Complete REST endpoint documentation
CLI Commands Command-line interface reference
Examples Real-world patterns including worker integration

Related Documentation:

Was this page helpful?