Documentation

Production vs SMS-Dev

Understanding the key differences between local development and production Relay API.

Important

SMS-Dev is designed for local development only. Production Relay API has additional security, compliance, and billing features required for real SMS operations.

Authentication

SMS-Dev (Local)

✓ No authentication required
✓ Open for localhost access
✓ Instant testing without setup
✗ Never use in production

Production Relay API

✓ AWS Cognito phone-based auth
✓ API key authentication required
✓ Session-based dashboard access
✓ AES-256-GCM encrypted keys

Migration Steps

Sign up at app.relay.works
Complete phone-based authentication (OTP via SMS)
Generate an API key from the dashboard
Add Authorization: Bearer your-api-key header to all requests
Update base URL from localhost:4001 to https://api.relay.works

Template System

Critical Production Requirement

Starter tier ($19/mo) users MUST use approved templates. Raw message sending is blocked to maintain carrier compliance on shared numbers.

SMS-Dev (Local)

• Both raw messages (POST /v1/messages) and templates (POST /v1/messages/send-template) supported
• Mock template catalog with 5 sample templates
• No compliance restrictions
• No "Sent by Relay" signature appending
• Unlimited testing

Production Relay API

• Starter tier: Template-only (raw messages return 402 error)
• Paid tiers: Both raw messages and templates supported
• Curated template catalog from @relay-works/templates
• Category restrictions: Only 2FA and CUSTOMER_CARE on Starter tier
• Automatic "- Sent by Relay" signature for Starter tier
• Template validation with variable interpolation

Example: Starter Tier Template Send

// Production Starter tier - MUST use template endpoint
const response = await fetch('https://api.relay.works/v1/messages/send-template', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer rly_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template: 'otp-verification',
    to: '+1234567890',
    data: {
      code: '123456',
      expiry: '10'
    }
  })
})

// Result: "Your verification code is 123456. It expires in 10 minutes. - Sent by Relay"
// Note the automatic signature appending for Starter tier

Subscription & Quotas

SMS-Dev (Local)

✓ Unlimited free messages
✓ No subscription required
✓ No quota enforcement
✓ $0.01 mock cost per message

Production Relay API

• Free tier: Cannot send SMS (402 error)
• Starter tier: $19/mo + $0.02/message overage
• Quota enforcement via database RPC
• Stripe Meter Events for billing

Production Subscription Tiers

Free Tier

Dashboard access only. SMS sending blocked with 402 Payment Required error.

Starter Tier ($19/mo)

• Shared phone number
• Template-only sending (2FA & CUSTOMER_CARE)
• Automatic "- Sent by Relay" signature
• $0.02 per message overage billing

Paid Tiers (Future)

Dedicated numbers, custom templates, no signature appending, higher quotas.

Rate Limiting

SMS-Dev (Local)

No rate limiting - unlimited requests for testing

Production Relay API

• Global: 1,000 requests per 15 minutes
• Per API key: 100 requests per minute
• Distributed via Redis (Upstash)
• Returns 429 Too Many Requests

Webhooks

SMS-Dev (Local)

• Simple webhook simulation for testing
• Inbound message simulation via POST /v1/webhooks/simulate-inbound
• Configuration via POST /v1/webhooks/configure
• No retry logic or circuit breakers
• No signing or idempotency

Production Relay API

• AWS SNS webhook delivery with signature validation
• Event types: message.sent, message.failed, message.delivered
• Rate limiting and circuit breaker patterns
• Retry logic with exponential backoff
• Webhook signing for security
• Database-persisted URLs per workspace

SMS Delivery

SMS-Dev (Local)

• In-memory simulation (no real SMS)
• Instant delivery simulation
• WebSocket updates to Virtual Phone UI
• Status progression: queued → sent → delivered

Production Relay API

• AWS End User Messaging via Pinpoint SMS Voice V2
• Real SMS delivery to phone numbers
• Delivery status callbacks from AWS
• Sentry integration for distributed tracing

10DLC Compliance

What is 10DLC?

10DLC (10-Digit Long Code) is a US carrier compliance framework for application-to-person (A2P) SMS messaging. All commercial SMS must register brands and campaigns.

SMS-Dev (Local)

• No 10DLC requirements (local testing)
• No brand or campaign registration
• No compliance validation

Production Relay API

• 10DLC brand and campaign registration system
• Supabase Edge Function for compliance validation
• Campaign type restrictions (2FA, CUSTOMER_CARE for Starter)
• Template compliance checking
• DLC applications router: POST /v1/dlc-applications

Migration Checklist

Create account at app.relay.works with phone authentication

Subscribe to Starter tier

$19/mo required to send SMS (free tier cannot send)

Generate API key

Create and securely store your API key from dashboard

Update code to use templates

Switch to POST /v1/messages/send-template for Starter tier

Add authentication headers

Include Authorization: Bearer your-api-key in all requests

Update base URL

Change from http://localhost:4001 to https://api.relay.works

Implement webhook handling

Add endpoint to receive delivery status updates

Handle rate limits

Implement retry logic for 429 responses

Test in production

Send test messages to verify end-to-end flow

Next Steps

API Reference

Explore the complete API documentation

View API Docs →

Production Relay

Get Started →

Code Examples

See template usage examples

View Examples →