Rate Limiting

Relay enforces rate limits on email sending to protect your SES sender reputation, prevent abuse, and ensure fair resource sharing across tenants. Limits apply across four time windows.

Default Rate Limits

Window	Default Limit	Purpose
Per second	10 emails	Prevents burst overload
Per minute	100 emails	Smooths short-term spikes
Per hour	2,000 emails	Controls sustained sending
Per day	40,000 emails	Overall daily cap

All four windows are checked on every send request. If any window is exceeded, the request is rejected.

How Rate Limiting Works

1. On each send request, Relay checks all four rate limit counters for your tenant
2. If all counters are below their limits, the email sends and all counters increment
3. If any counter is at its limit, the request returns 429 Too Many Requests
4. Counters reset automatically when their time window expires (TTL-based in Cosmos DB)

For batch sends, each email in the batch counts individually. A batch of 50 emails increments all counters by 50.

429 Response

When rate limited, the API returns:

{
  "error": "Rate limit exceeded",
  "retry_after": 5
}

The Retry-After header indicates how many seconds to wait before retrying. Respect this header to avoid repeated rejections.

Handling Rate Limits in Your Application

async function sendWithRetry(email: SendRequest, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.theonerelay.app/api/send', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Relay-Key': apiKey,
      },
      body: JSON.stringify(email),
    });

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response.json();
  }
  throw new Error('Rate limit exceeded after max retries');
}

Custom Rate Limits

Tenant rate limits can be customized in Settings:

1. Go to Settings (gear icon)
2. Under Rate Limits, adjust any of the four windows
3. Click Save

Custom limits can also be set per API key for finer control (e.g., a test key with lower limits than production).

ℹ️Rate limits must have a minimum value of 1 for all windows. Setting a window to 0 is not allowed.

SES Warm-Up Schedule

New SES accounts start with lower sending limits that increase over time as you build a sending reputation. Relay rate limits should align with your SES account limits.

SES Account Age	Typical SES Limit	Recommended Relay Limit
New (sandbox)	200/day, 1/second	Match SES limits
1-2 weeks	10,000/day	8,000/day
1 month	50,000/day	40,000/day
3+ months	100,000+/day	As needed

💡Request a SES sending limit increase through the AWS console once you've established a positive sending reputation (bounce rate below 5%, complaint rate below 0.1%).

Monitoring Rate Limit Usage

The Analytics page shows daily email volume. If you're consistently hitting rate limits:

1. Check Analytics for volume trends
2. Identify which products/integrations drive the most volume (use tags)
3. Consider increasing limits if volume is legitimate
4. Stagger batch sends throughout the day rather than sending all at once
5. Use batch send with controlled pacing rather than rapid individual sends