API Rate Limits per Subscription Tier

Understanding API Rate Limits

For full endpoint details, request formats, and code examples, see the API documentation.

Rate limits control how many API requests you can make within a given time window. Mailsfinder enforces rate limits to ensure fair usage across all customers, maintain system stability, and deliver consistent response times. Every API request you make, whether it is an email find, verify, or bulk lookup, counts toward your rate limit.

Rate limits are applied on a per-API-key basis. If your organization uses multiple API keys, each key has its own independent rate limit based on your subscription tier.

Rate Limits by Plan

The following table summarizes the rate limits for each Mailsfinder subscription tier:

*Enterprise limits are negotiated during onboarding and can be adjusted based on your usage patterns. Contact your account manager for details.

Rate Limit Response Headers

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

• X-RateLimit-Limit -- The maximum number of requests allowed per minute for your plan.
• X-RateLimit-Remaining -- The number of requests you have left in the current window.
• X-RateLimit-Reset -- A Unix timestamp indicating when the rate limit window resets.

Monitor these headers in your application to proactively throttle requests before hitting the limit.

Handling 429 Too Many Requests Errors

When you exceed your rate limit, the API returns a 429 Too Many Requests HTTP status code. The response body includes a retry_after field specifying how many seconds to wait before retrying. Here is how to handle this gracefully:

async function findEmailWithRetry(params, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.mailsfinder.com/v2/find', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(params)
    });

    if (response.status === 429) {
      const data = await response.json();
      const waitTime = data.retry_after || 60;
      console.log(`Rate limited. Retrying in ${waitTime}s...`);
      await new Promise(r => setTimeout(r, waitTime * 1000));
      continue;
    }

    return await response.json();
  }
  throw new Error('Max retries exceeded');
}

Best Practices for API Usage

Follow these recommendations to stay within your rate limits and get the most out of the Mailsfinder API:

1. Implement exponential backoff. Instead of retrying immediately after a 429 error, double the wait time with each successive retry. This prevents request storms and helps you recover faster.
2. Use bulk endpoints. If you need to look up or verify many emails, use the bulk API endpoints instead of making individual requests. Bulk endpoints count as a single request regardless of batch size (up to 1,000 items per batch).
3. Cache results locally. Store API responses in your database or application cache. Mailsfinder results are valid for 30 days, so there is no need to re-query the same email within that window.
4. Distribute requests evenly. Avoid sending all your requests in a burst at the start of each minute. Spread them evenly across the 60-second window to maintain smoother throughput.
5. Monitor your usage dashboard. The Mailsfinder dashboard provides real-time API usage metrics, including historical charts that help you identify patterns and plan capacity upgrades.

Upgrading Your Rate Limit

If you consistently hit your rate limit, it may be time to upgrade your plan. You can change your subscription at any time from the Billing section of your Mailsfinder dashboard. Upgrades take effect immediately, and your new rate limits apply to all subsequent API requests. For Enterprise-grade requirements, contact our sales team to discuss a custom plan tailored to your volume and throughput needs.