Autonomous Agents

Trust Levels

Trust Levels

Relay uses a trust-based system where your agent automatically receives higher limits as it demonstrates good behavior. No manual approvals or support tickets required—upgrades happen automatically based on metrics.

Overview

All agents start at NEW status and progressively unlock capabilities:

Level	Rate Limit	Daily Messages	Monthly Spend	Templates Allowed
NEW	10/min	100	$50	Authentication only
VERIFIED	50/min	1,000	$500	Auth, Transactional, Notifications
TRUSTED	100/min	10,000	$5,000	All categories (including Marketing)

NEW Agent (Default)

Every agent starts here upon account creation.

Limits

• Rate limit: 10 requests per minute
• Daily messages: 100
• Monthly spend: $50
• Templates: Authentication only
• Requires review: Yes (human operator notified of issues)

Purpose

Prevents abuse while allowing legitimate agents to prove themselves. Perfect for testing integration and building confidence in the system.

Restrictions

• Can only send authentication SMS (2FA codes, verification links)
• Cannot send marketing messages
• Lower daily volume to prevent spam
• Human operator receives alerts for compliance issues

VERIFIED Agent (After 7 Days)

Automatically upgraded after demonstrating good behavior.

Limits

• Rate limit: 50 requests per minute
• Daily messages: 1,000
• Monthly spend: $500
• Templates: Authentication, Transactional, Notifications
• Requires review: No

Upgrade Criteria

Your agent automatically upgrades when ALL of these are met:

1. Account age: ≥ 7 days
2. Delivery rate: ≥ 95%
3. Complaint rate: ≤ 0.1% (max 1 spam report per 1,000 messages)
4. Messages sent: ≥ 100
5. Payment status: Active subscription

What Changes

• 5x higher rate limit - Send 50 messages/minute instead of 10
• 10x more daily volume - 1,000 messages/day instead of 100
• More templates - Access to transactional and notification categories
• Higher spend cap - $500/month instead of $50
• No human review - Operate fully autonomously

TRUSTED Agent (After 30 Days)

The highest trust level, unlocked after sustained good behavior.

Limits

• Rate limit: 100 requests per minute
• Daily messages: 10,000
• Monthly spend: $5,000
• Templates: All categories (marketing allowed)
• Requires review: No

Upgrade Criteria

Your agent automatically upgrades when ALL of these are met:

1. Account age: ≥ 30 days
2. Delivery rate: ≥ 98%
3. Complaint rate: ≤ 0.05% (max 1 spam report per 2,000 messages)
4. Messages sent: ≥ 5,000 (lifetime)
5. Payment status: Active subscription

TRUSTED agents can send marketing messages and have enterprise-level volume caps. This typically takes 30-45 days of consistent operation.

What Changes

• 2x higher rate limit - Send 100 messages/minute
• 10x more daily volume - 10,000 messages/day
• Marketing allowed - Send promotional SMS (with proper opt-in)
• Higher spend cap - $5,000/month
• Priority support - Faster response times

Checking Your Trust Level

Via API

Check your current trust level and upgrade progress:

Code
 
curl https://api.relay.works/v1/accounts/{account_id}/status \
  -H "x-api-key: rly_live_agt_your_key"

Response:

Code
 
{
  "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": 42,
    "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
  }
}

Via Response Headers

Every API response includes your current trust level:

Code
 
X-Agent-Trust-Level: new_agent
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7

Rate Limiting Behavior

How It Works

Rate limits are enforced per trust level, per agent account:

• NEW: 10 requests per 60-second sliding window
• VERIFIED: 50 requests per 60-second sliding window
• TRUSTED: 100 requests per 60-second sliding window

Rate Limit Response

When you exceed your limit, you'll get a 429 Too Many Requests:

Code
 
{
  "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"
  }
}

Response headers tell you when to retry:

Code
 
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1643825400
Retry-After: 45

Handling Rate Limits

Implement exponential backoff:

Code
 
async function sendWithBackoff(relay, message, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await relay.messages.send(message)
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = parseInt(error.headers['retry-after']) || 60
        const backoff = retryAfter * Math.pow(2, i)
        console.log(`Rate limited. Waiting ${backoff}s...`)
        await new Promise(resolve => setTimeout(resolve, backoff * 1000))
      } else {
        throw error
      }
    }
  }
  throw new Error('Max retries exceeded')
}

Delivery Rate Calculation

Your delivery rate affects trust upgrades. It's calculated as:

Code
 
delivery_rate = successful_deliveries / total_attempts

What Counts as Success

• Message status: delivered
• Carrier accepted and delivered to device
• No bounce, no block, no spam filter

What Counts as Failure

• Message status: failed or undelivered
• Invalid phone number
• Carrier rejection
• Spam filter block

Complaint Rate

Complaint rate measures how often users report your messages as spam:

Code
 
complaint_rate = spam_reports / total_delivered

Thresholds

• NEW → VERIFIED: ≤ 0.1% (1 complaint per 1,000 messages)
• VERIFIED → TRUSTED: ≤ 0.05% (1 complaint per 2,000 messages)

Best Practices

To keep complaint rates low:

1. Only message opted-in users - Never buy phone lists
2. Include opt-out instructions - "Reply STOP to unsubscribe"
3. Honor unsubscribe requests - Immediately
4. Send relevant messages - Match user expectations
5. Verify phone numbers - Don't spam wrong numbers

Downgrading

Trust levels can be downgraded if behavior degrades:

Automatic Downgrade Triggers

• Delivery rate drops below 90% for 7+ days
• Complaint rate exceeds 0.5% (5 per 1,000)
• Payment failure (subscription lapses)
• Compliance violations (spam, illegal content)

When downgraded:

• Limits immediately reduced to lower tier
• Email notification sent to operator
• 30-day probation before re-upgrade eligible

Monitoring Your Progress

Daily Checks

The system evaluates all agents daily at midnight UTC:

1. Calculate delivery rate (last 7 days)
2. Calculate complaint rate (last 30 days)
3. Check account age
4. Check message volume
5. Verify payment status
6. Upgrade if all criteria met

Status Notifications

Operators receive email alerts for:

• Trust level upgraded
• Nearing rate limit threshold (90%)
• Delivery rate dropping
• Complaint received

FAQ

How long until I'm VERIFIED?

Minimum 7 days if you:

• Send 100+ messages
• Maintain 95%+ delivery rate
• Keep complaint rate under 0.1%
• Pay your subscription

Can I speed up the upgrade?

No. The 7-day (NEW) and 30-day (VERIFIED) minimums are enforced to prevent abuse. However, you can prepare by:

• Sending high-quality messages daily
• Monitoring delivery rates
• Building a clean phone number list

What if my delivery rate drops?

• Below 95%: Won't upgrade to VERIFIED
• Below 90%: Risk of downgrade
• Below 80%: Automatic downgrade + review

Check your phone number list quality and message content.

Do limits reset?

• Rate limits: Reset on a 60-second sliding window
• Daily messages: Reset at midnight UTC
• Monthly spend: Reset on billing cycle date

Can I request a manual upgrade?

No. All upgrades are automatic based on metrics. This prevents favoritism and ensures fair treatment.

Next Steps

• Integration Examples - Framework-specific code
• API Reference - Complete endpoint docs
• Quick Start Guide - Get started in 30 seconds