Rate Limiting

Overview

thePurplebox API implements rate limiting to ensure fair usage and system stability. Rate limits vary based on your subscription plan and apply to both API calls and email sending.

Rate Limits by Plan

Free Plan

The Free plan has the following rate limits:

3 requests per minute - Combined limit for both API calls and emails sent
Applies to all endpoints including email sending and API operations

Paid Plans

All paid plans (Starter, Growth, Business, Enterprise) have separate limits:

50 emails per minute - For transactional email sending
50 API calls per minute - For all other API operations (domains, retrieving emails, logs, etc.)

How Rate Limiting Works

Rate limits are calculated on a per-minute rolling window basis. The counter resets every minute from your first request.

Example Scenarios

Free Plan

Time: 10:00:00 - Send email #1 ✓
Time: 10:00:20 - Send email #2 ✓
Time: 10:00:40 - Send email #3 ✓
Time: 10:00:50 - Send email #4 ✗ (Rate limit exceeded)
Time: 10:01:01 - Counter resets, send email #5 ✓

Paid Plan - Emails

Send 50 emails within one minute ✓
51st email ✗ (Rate limit exceeded)
Wait for counter to reset
Continue sending ✓

Paid Plan - API Calls

Make 50 API calls (GET emails, verify domain, etc.) within one minute ✓
51st API call ✗ (Rate limit exceeded)
Wait for counter to reset
Continue API operations ✓

Rate Limit Headers

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

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700654400

Header Descriptions

number

The maximum number of requests allowed in the current time window.

number

The number of requests remaining in the current time window.

number

Unix timestamp indicating when the rate limit counter resets.

Rate Limit Exceeded Response

When you exceed your rate limit, the API returns a 429 Too Many Requests status code:

{
  "status": 429,
  "message": "Rate limit exceeded. Please try again later.",
  "data": {
    "retry_after": 45,
    "limit": 3,
    "window": "1 minute"
  }
}

Response Fields

number

HTTP status code. Always 429 for rate limit errors.

string

Human-readable error message.

object

Additional information about the rate limit.

Show properties

number

Number of seconds to wait before making another request.

number

Your current rate limit threshold.

string

The time window for the rate limit (e.g., “1 minute”).

Best Practices

1. Monitor Rate Limit Headers

Always check the X-RateLimit-Remaining header before making bulk operations:

const response = await fetch('https://api.thepurplebox.io/v1/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(emailData)
});

const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

console.log(`Requests remaining: ${remaining}`);
console.log(`Resets at: ${new Date(reset * 1000)}`);

2. Implement Exponential Backoff

When you receive a 429 response, implement exponential backoff:

async function sendWithRetry(emailData, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('https://api.thepurplebox.io/v1/send', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(emailData)
      });

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

      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

3. Batch Operations When Possible

For paid plans, spread out your requests to stay within limits:

// Instead of sending 150 emails immediately
// Batch them in groups of 50 per minute

async function batchSendEmails(emails) {
  const batchSize = 50;
  
  for (let i = 0; i < emails.length; i += batchSize) {
    const batch = emails.slice(i, i + batchSize);
    
    // Send batch
    await Promise.all(batch.map(email => sendEmail(email)));
    
    // Wait 1 minute before next batch
    if (i + batchSize < emails.length) {
      await new Promise(resolve => setTimeout(resolve, 60000));
    }
  }
}

Upgrading Your Plan

If you consistently hit rate limits, consider upgrading your plan:

Free Plan: 3 requests/min
Paid Plans: 50 emails/min + 50 API calls/min

Upgrade your plan to increase your rate limits.

Need Higher Limits?

If you have a good sending reputation and need higher rate limits, we can increase your limits on a case-by-case basis. Contact us at hello@thepurplebox.io to discuss your sending needs and reputation metrics.

API Documentation

Transactional

Emails

Domains

API Keys

Overview

Rate Limits by Plan

Free Plan

Paid Plans

How Rate Limiting Works

Example Scenarios

Free Plan

Paid Plan - Emails

Paid Plan - API Calls

Rate Limit Headers

Header Descriptions

Rate Limit Exceeded Response

Response Fields

Best Practices

1. Monitor Rate Limit Headers

2. Implement Exponential Backoff

3. Batch Operations When Possible

Upgrading Your Plan

Need Higher Limits?

​Overview

​Rate Limits by Plan

​Free Plan

​Paid Plans

​How Rate Limiting Works

​Example Scenarios

​Free Plan

​Paid Plan - Emails

​Paid Plan - API Calls

​Rate Limit Headers

​Header Descriptions

​Rate Limit Exceeded Response

​Response Fields

​Best Practices

​1. Monitor Rate Limit Headers

​2. Implement Exponential Backoff

​3. Batch Operations When Possible

​Upgrading Your Plan

​Need Higher Limits?

Overview

Rate Limits by Plan

Free Plan

Paid Plans

How Rate Limiting Works

Example Scenarios

Free Plan

Paid Plan - Emails

Paid Plan - API Calls

Rate Limit Headers

Header Descriptions

Rate Limit Exceeded Response

Response Fields

Best Practices

1. Monitor Rate Limit Headers

2. Implement Exponential Backoff

3. Batch Operations When Possible

Upgrading Your Plan

Need Higher Limits?