Rate Limits

Overview

Rate limits protect the API from abuse and ensure fair usage for all users. Limits are applied per organization using an in-memory sliding window.

API Request Limits

Tier	Requests/Second	Requests/Minute	Requests/Day
Standard	10	500	50,000
High Volume	50	2,000	200,000

Need higher limits? Contact us to discuss your volume requirements.

Email Sending

Unosend uses a credit-based system. 1 credit = 1 email. Contact us for pricing and volume details.

No subscription — buy credits when you need them
Email size limit: 15 MB (headers + body + inline images + attachments)

Domain Sending Limit

There is a global daily limit of 200,000 emails per sender domain across all plans. This protects shared infrastructure and ensures deliverability.

Domain Creation Rate Limit

All plans include unlimited domains. To prevent abuse, domain creation is rate limited to 10 domains per hour per organization. This is a velocity cap — there is no limit on the total number of domains you can add.

Limit	Value
Domains per hour	10
Total domains	Unlimited (all plans)

If you exceed this limit, the API returns 429 Too Many Requests. Wait and retry after a few minutes.

Rate Limit Headers

Every API response includes headers to help you track your rate limit status:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when window resets
`Retry-After`	Seconds to wait (only on 429 response)

Example Response Headers

response-headers.txt

HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 485
X-RateLimit-Reset: 1705320060
Content-Type: application/json

Check Current Usage

You can check your current rate limit status with any API request by inspecting the response headers, or use the usage endpoint:

Terminal

curl -X GET "https://api.unosend.co/usage" \
  -H "Authorization: Bearer un_your_api_key" \
  -i

Response

response.json

{
  "credits_remaining": 37550,
  "credits_used": 12450,
  "credits_total": 50000,
  "credits_expire_at": "2026-07-01T00:00:00Z"
}

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

rate-limit-response.json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "retry_after": 60
  }
}

Implementing Retry Logic

# Use --retry flag for automatic retries
curl -X POST "https://api.unosend.co/emails" \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  --retry 3 \
  --retry-delay 5 \
  -d '{"from": "hello@yourdomain.com", "to": "user@example.com", "subject": "Hello", "html": "<p>Hi!</p>"}'

async function sendEmailWithRetry(
  payload: EmailPayload,
  maxRetries: number = 3
): Promise<Response> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.unosend.co/emails', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });
    
    if (response.status === 429) {
      const retryAfter = parseInt(
        response.headers.get('Retry-After') || '60'
      );
      console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
      await sleep(retryAfter * 1000);
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

import requests
import time

def send_email_with_retry(payload, max_retries=3):
    api_key = "un_your_api_key"
    
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.unosend.co/emails",
            headers={
                "Authorization": f"Bearer {api_key}",
                "Content-Type": "application/json"
            },
            json=payload
        )
        
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Waiting {retry_after} seconds...")
            time.sleep(retry_after)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")

Exponential Backoff

For robust retry logic, use exponential backoff with jitter to avoid thundering herd:

exponential-backoff.ts

async function sendWithExponentialBackoff(
  payload: EmailPayload,
  maxRetries: number = 5
): Promise<Response> {
  const baseDelay = 1000; // 1 second
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.unosend.co/emails', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload)
      });
      
      if (response.status === 429) {
        // Calculate delay with exponential backoff + jitter
        const delay = baseDelay * Math.pow(2, attempt);
        const jitter = Math.random() * 1000;
        const waitTime = delay + jitter;
        
        console.log(`Rate limited. Waiting ${waitTime}ms (attempt ${attempt + 1})`);
        await sleep(waitTime);
        continue;
      }
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }
      
      return response;
      
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      
      const delay = baseDelay * Math.pow(2, attempt);
      await sleep(delay);
    }
  }
  
  throw new Error('Max retries exceeded');
}

Queue Pattern for Bulk Sending

For sending many emails, use a queue with rate limiting to stay within limits:

rate-limited-queue.ts

class RateLimitedQueue {
  private queue: EmailPayload[] = [];
  private processing = false;
  private requestsPerSecond: number;
  
  constructor(requestsPerSecond: number = 10) {
    this.requestsPerSecond = requestsPerSecond;
  }
  
  async add(payload: EmailPayload): Promise<void> {
    this.queue.push(payload);
    this.process();
  }
  
  private async process(): Promise<void> {
    if (this.processing) return;
    this.processing = true;
    
    const interval = 1000 / this.requestsPerSecond;
    
    while (this.queue.length > 0) {
      const payload = this.queue.shift()!;
      
      try {
        await sendEmailWithRetry(payload);
      } catch (error) {
        console.error('Failed to send email:', error);
      }
      
      await sleep(interval);
    }
    
    this.processing = false;
  }
}

// Usage
const queue = new RateLimitedQueue(10); // 10 req/sec

for (const recipient of recipients) {
  queue.add({
    from: 'hello@yourdomain.com',
    to: recipient.email,
    subject: 'Hello!',
    html: '<p>Your email content</p>'
  });
}

For bulk sending, consider using the /emails/batch endpoint which allows up to 100 emails per request, significantly reducing API calls.

Best Practices

Monitor rate limit headers

Check X-RateLimit-Remaining and slow down before hitting limits.

Use batch endpoints

Send multiple emails in one request using POST /emails/batch to reduce API calls.

Implement queuing

Queue emails during high-traffic periods and process them at a controlled rate.

Use webhooks instead of polling

Instead of polling for status, use webhooks to receive delivery updates asynchronously.

Cache responses when possible

Cache responses from endpoints like GET /domains to reduce unnecessary requests.

Need Higher Limits?

If you need higher rate limits for your use case, upgrade your plan or contact us for Enterprise options with custom limits.

Getting Started

Guides

Resources

Overview

API Request Limits

Email Sending

Domain Sending Limit

Domain Creation Rate Limit

Rate Limit Headers

Example Response Headers

Check Current Usage

Response

Handling Rate Limits

Implementing Retry Logic

Exponential Backoff

Queue Pattern for Bulk Sending

Best Practices

Need Higher Limits?

​Overview

​API Request Limits

​Email Sending

​Domain Sending Limit

​Domain Creation Rate Limit

​Rate Limit Headers

​Example Response Headers

​Check Current Usage

​Response

​Handling Rate Limits

​Implementing Retry Logic

​Exponential Backoff

​Queue Pattern for Bulk Sending

​Best Practices

​Need Higher Limits?

Overview

API Request Limits

Email Sending

Domain Sending Limit

Domain Creation Rate Limit

Rate Limit Headers

Example Response Headers

Check Current Usage

Response

Handling Rate Limits

Implementing Retry Logic

Exponential Backoff

Queue Pattern for Bulk Sending

Best Practices

Need Higher Limits?