Skip to main content

​
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
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 ✓

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

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

​
X-RateLimit-Limit
number
The maximum number of requests allowed in the current time window.
​
X-RateLimit-Remaining
number
The number of requests remaining in the current time window.
​
X-RateLimit-Reset
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

​
status
number
HTTP status code. Always 429 for rate limit errors.
​
message
string
Human-readable error message.
​
data
object
Additional information about the rate limit.

​
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 [email protected] to discuss your sending needs and reputation metrics.