Rate Limits

API requests are rate limited to ensure fair usage and platform stability.

Limits by Plan

Plan	API Requests	Emails/Month	Burst Limit
Free	100/minute	3,000	10/second
Starter	500/minute	10,000	25/second
Pro	1,000/minute	50,000	50/second
Scale	2,000/minute	200,000	100/second
Enterprise	Custom	Custom	Custom

Rate Limit Headers

Every API response includes headers with rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": {
    "code": "rate_limit",
    "message": "Rate limit exceeded. Please retry after 30 seconds."
  }
}

Best Practices

Implement exponential backoff

When rate limited, wait and retry with increasing delays.

backoff.ts

import { RateLimitError } from '@veilmail/sdk';

async function sendWithBackoff(params, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.emails.send(params);
    } catch (error) {
      if (error instanceof RateLimitError && attempt < maxRetries - 1) {
        const delay = error.retryAfter
          ? error.retryAfter * 1000
          : Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Monitor rate limit headers

Track your remaining quota and slow down before hitting the limit.

Use bulk operations

For campaigns, use the campaigns API instead of sending individual emails to reduce the number of API calls.

Queue requests

Implement a queue to spread requests over time rather than sending bursts.

Need higher limits?

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