Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.unosend.co/llms.txt

Use this file to discover all available pages before exploring further.

​
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

TierRequests/SecondRequests/MinuteRequests/Day
Standard1050050,000
High Volume502,000200,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.
LimitValue
Domains per hour10
Total domainsUnlimited (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:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed per window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when window resets
Retry-AfterSeconds 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>"}'

​
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

1

Monitor rate limit headers

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

Use batch endpoints

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

Implement queuing

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

Use webhooks instead of polling

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

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.