Getting Started

Installation Guide

Get up and running with Relay SMS in minutes. This guide covers everything you need to start sending messages.

Who Can Use Relay

Relay is currently available for businesses sending SMS to United States and Canada customers.

Great fit for:

• US-based SaaS companies and startups
• Healthcare platforms serving North American patients
• Fintech and banking applications
• E-commerce businesses in US/Canada markets
• Authentication providers for US/Canada users
• International companies where US/Canada represents a significant market

Regional focus: Relay supports US and Canada destinations only. We've optimized our infrastructure for North American messaging before expanding internationally.

Create Your Account

1. Visit app.relay.works
2. Complete the 4-step onboarding:
   • Company Setup - Enter your business details
   • API Key Generation - Automatically created for you
   • Demo SMS Test - Send a test message
   • Subscription - Choose the Starter tier ($19/mo)
3. Complete payment to activate your account

You're now ready to send SMS messages!

Get Your API Key

Your API key is automatically generated during onboarding. You can view it anytime:

1. Navigate to Dashboard > Settings > API Keys
2. Your key format: rly_sk_1234567890abcdef...
3. Copy and store it securely

Store Your API Key

Create a .env file in your project root:

.env
 
RELAY_API_KEY=rly_sk_your_api_key_here
RELAY_API_BASE_URL=https://api.relay.works

Add .env to your .gitignore:

.gitignore
 
.env

Send Your First SMS

Using cURL

The simplest way to test your setup:

Code
 
# Set your API key
export RELAY_API_KEY="rly_sk_your_api_key_here"

# Send an SMS
curl -X POST https://api.relay.works/v1/messages \
  -H "x-api-key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "message": "Hello from Relay!"
  }'

Expected response:

Code
 
{
  "id": "msg_abc123",
  "to": "+15551234567",
  "message": "Hello from Relay!",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00Z"
}

Understanding the Response

• id: Unique message identifier for tracking
• status: Current delivery status (queued, sent, delivered, failed)
• created_at: Timestamp when message was created

What Happens Next?

1. Message is queued for delivery
2. Sent to the carrier within seconds
3. Delivered to the recipient's device
4. Status updates available via webhooks or API polling

Starter Tier Features

Your Starter tier subscription includes:

• 1,500 SMS messages/month included
• $0.02 per message after 1,500
• Shared Relay number - Automatically assigned
• "Sent by Relay" suffix - Added to all messages
• Delivery tracking - Real-time status updates
• API access - Full API capabilities

No phone number purchase needed - start sending immediately!

Next Steps

For Quick Setup

• Development Setup - Set up local testing environment
• Messages API - Explore all message features

For Production Use

• Authentication - Manage API keys
• Webhooks - Real-time delivery notifications
• SMS Basics - Character limits, encoding, best practices

Language-Specific Examples

All API endpoints include code examples for:

• Node.js - See Messages API
• Python - See Messages API
• cURL - See Messages API
• Next.js Server Actions - See Messages API

Environment Configuration

Development vs Production

Use environment variables to switch between environments:

Code
 
// Development - use SMS-dev for free local testing
const apiUrl = process.env.NODE_ENV === 'development'
  ? 'http://localhost:4001/v1'  // SMS-dev local server
  : 'https://api.relay.works/v1'; // Production API

const apiKey = process.env.RELAY_API_KEY;

Production Deployment

Set environment variables in your hosting platform:

Vercel:

Code
 
vercel env add RELAY_API_KEY

Railway:

Code
 
railway variables set RELAY_API_KEY=rly_sk_your_key

Heroku:

Code
 
heroku config:set RELAY_API_KEY=rly_sk_your_key

Getting Help

• Documentation: Browse the complete API Reference
• Support: Email support@relay.works
• Status: Check system uptime and status

---

You're all set! Your Relay account is ready to send SMS messages. Check out the Development Setup guide to set up local testing with SMS-dev.