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

    style CommsService fill:#e8f5e8,stroke:#2e7d32,stroke-width:3px
    style CLI fill:#e1f5fe,stroke:#1976d2,stroke-width:2px
    style API fill:#e1f5fe,stroke:#1976d2,stroke-width:2px
    style Resend fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Twilio fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style Backend fill:#e1f5fe,stroke:#1976d2,stroke-width:2px
    style ArqQueues fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style Redis fill:#ffebee,stroke:#c62828,stroke-width:2px

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

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.email import send_email_simple
from app.services.comms.sms import send_sms_simple
from app.services.comms.call import make_call_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: