OVERVIEW

• ├─ What: SMS API optimized for autonomous agents
• ├─ Trust-Based System: Progressive rate limits based on behavior
• └─ Zero-Touch Onboarding: Full API provisioning without human interaction

GETTING STARTED

• ├─ Endpoint: POST /v1/accounts/autonomous
• ├─ Authentication: None required for account creation
• ├─ Response: API key (one-time reveal), workspace ID, payment link
• ├─ Payment: Required before sending any SMS
• └─ Time to Active Account: < 5 minutes (after payment)

TRUST LEVELS

ACCOUNT CREATION REQUEST

POST https://api.relay.works/v1/accounts/autonomous
Content-Type: application/json

{
  "agent": {
    "name": "your-agent-name",
    "framework": "anthropic-mcp|langchain|autogpt|openhands|other",
    "operator": "operator@example.com",
    "version": "1.0.0"
  },
  "use_case": {
    "category": "authentication|transactional|notifications|alerts|marketing",
    "description": "Brief description of intended use",
    "estimated_volume": "100-500/day|500-1000/day|1000+/day"
  },
  "payment": {
    "method": "stripe_link",
    "funding_source": "human_operator|agent_managed"
  }
}

ACCOUNT CREATION RESPONSE

{
  "account_id": "uuid",
  "workspace_id": "uuid",
  "api_key": "rly_live_agt_[key]",  # ONE TIME ONLY - store securely
  "status": "active",
  "limits": {
    "daily_messages": 100,
    "monthly_spend": 50,
    "rate_per_minute": 10
  },
  "payment": {
    "stripe_link": "https://app.relay.works/api/payment/setup?workspace=uuid",
    "instructions": "Complete payment to activate account and start sending SMS"
  },
  "compliance": {
    "status": "approved",
    "next_steps": [
      "Complete payment to activate account",
      "Send first message to validate use case",
      "Limits increase automatically after 100 successful sends"
    ]
  },
  "webhooks": {
    "status_url": "https://api.relay.works/v1/accounts/uuid/status",
    "auto_subscribe": true
  },
  "is_initial_response": true
}

SENDING MESSAGES

⚠️ Payment Required: All SMS sends will return 402 Payment Required until subscription is active

POST https://api.relay.works/v1/messages/send-template
Authorization: Bearer rly_live_agt_[your_key]
Content-Type: application/json

{
  "to": "+1234567890",
  "template": "authentication",  # REQUIRED for Starter tier
  "data": {
    "code": "123456"
  }
}

📝 Template Required: All agents on Starter tier (all autonomous agents) must use pre-approved templates. Raw message bodies are not allowed.

PRICING

• ├─ Plan: Starter tier ($19/month)
• ├─ Included: 1,500 messages
• ├─ Overage: $0.025 per message
• ├─ Payment: Stripe Payment Link (required before sending)
• └─ No setup fees, no hidden costs

COMPLIANCE

• ├─ 10DLC: Automatic registration (no human action required)
• ├─ Templates: Pre-approved message patterns
• ├─ Categories: Authentication, transactional, notifications, alerts, marketing
• └─ US Carrier: Compliant with all major carriers (AT&T, T-Mobile, Verizon)

RATE LIMITS & HEADERS

Response Headers:

• ├─ X-RateLimit-Limit: Maximum requests per window
• ├─ X-RateLimit-Remaining: Requests remaining
• ├─ X-RateLimit-Reset: Unix timestamp for reset
• └─ X-Agent-Trust-Level: Current trust level

429 Response (Rate Limit Exceeded):

{
  "error": "rate_limit_exceeded",
  "trust_level": "new_agent",
  "current_limit": 10,
  "next_level": {
    "name": "verified_agent",
    "limit": 50,
    "requirements": "7 days age + 95% delivery + 100 messages + payment"
  }
}

TRUST LEVEL UPGRADE TRACKING

GET https://api.relay.works/v1/accounts/:accountId/status

Response:
{
  "status": "active",
  "trust_level": "new_agent",
  "account_age_days": 3,
  "limits": {
    "daily_messages": 100,
    "rate_per_minute": 10,
    "monthly_spend": 50,
    "allowed_templates": ["authentication"]
  },
  "usage": {
    "total_messages_sent": 45,
    "subscription_plan": "starter"
  },
  "compliance": {
    "status": "approved",
    "requires_review": true
  },
  "next_upgrade": {
    "to_level": "verified_agent",
    "criteria": {
      "min_age_days": 7,
      "min_messages": 100,
      "min_delivery_rate": 0.95
    },
    "estimated_days_remaining": 4
  }
}

ERROR CODES

• ├─ 400: Invalid request (check template category, phone format)
• ├─ 401: Invalid API key
• ├─ 402: Payment required (subscription not active - complete payment link)
• ├─ 429: Rate limit exceeded (see upgrade requirements)
• ├─ 451: Template required (Starter tier must use templates)
• └─ 503: Service temporarily unavailable

TEMPLATE CATEGORIES

• ├─ authentication: OTP codes, 2FA verification
• ├─ transactional: Order confirmations, receipts
• ├─ notifications: Account alerts, reminders
• ├─ alerts: Security alerts, urgent updates
• └─ marketing: Promotional (requires TRUSTED trust level)

FRAMEWORK-SPECIFIC EXAMPLES

Anthropic MCP Integration

import os
import requests

# Assuming api_key is loaded from environment or config
api_key = os.getenv("RELAY_API_KEY")

mcp_server.register_tool(
  name="send_sms",
  fn=lambda to, template, data:
    requests.post(
      "https://api.relay.works/v1/messages/send-template",
      headers={"Authorization": f"Bearer {api_key}"},
      json={"to": to, "template": template, "data": data}
    )
)

LangChain Tool

import os
import requests
from langchain.tools import BaseTool

class RelaySMSTool(BaseTool):
    name = "send_sms"
    description = "Send SMS via Relay API"

    def _run(self, to: str, template: str, data: dict):
        return requests.post(
            "https://api.relay.works/v1/messages/send-template",
            headers={"Authorization": f"Bearer {os.getenv('RELAY_API_KEY')}"},
            json={"to": to, "template": template, "data": data}
        ).json()

AutoGPT Plugin

class RelaySMSPlugin(Plugin):
    def send_sms(self, to: str, message: str):
        # Template resolution handled by Relay
        return self.client.post("/v1/messages/send-template", {
            "to": to,
            "template": "notifications",
            "data": {"message": message}
        })

WEBHOOK DELIVERY TRACKING (Optional)

Configure webhook URL via API after account creation:

POST https://api.relay.works/v1/webhooks
Authorization: Bearer rly_live_agt_[your_key]

{
  "url": "https://your-agent.com/webhooks/sms",
  "events": ["message.status.updated"]
}

Webhook Payload:

{
  "event": "message.status.updated",
  "data": {
    "messageId": "uuid",
    "awsMessageId": "uuid",
    "to": "+1234567890",
    "from": "+1234567890",
    "status": "delivered",
    "timestamp": "ISO8601"
  },
  "timestamp": "ISO8601",
  "webhook_id": "uuid"
}

SUPPORT & ESCALATION

• ├─ Documentation: https://docs.relay.works
• ├─ Operator Contact: Escalations sent to agent.operator_email
• └─ Issue Reporting: support@relay.works

PHILOSOPHY

This API is designed for autonomous agents operating without human oversight. All operations are zero-touch: account creation, trust upgrades, payment, and compliance handling require no human intervention. The trust system rewards good behavior with automatic limit increases.

SECURITY

• ├─ API Keys: One-time reveal, never logged
• ├─ Rate Limiting: Progressive based on trust level
• ├─ Template Validation: Automatic compliance checking
• └─ Payment Security: Stripe Payment Links (PCI compliant)

GETTING HELP

If your agent encounters errors:

1. Check the error code and message
2. Review trust level requirements for upgrade path
3. Verify template category matches trust level
4. Contact operator email for urgent issues