Email API Rate Limiting: Design and Best Practices

When using the temp mail API, you'll encounter rate limits — how many calls per day, how many requests per second. This isn't punitive; it's essential API design. This guide explains why and how to optimize.

Why APIs Need Rate Limiting

Without limits, APIs face:

1. Resource abuse: a few users hog all resources
2. Cost overrun: each call costs server resources
3. Security risk: unlimited APIs invite DDoS

Rate limiting ensures fair resource allocation — everyone can use the API.

YYDS Mail Rate Limiting

Daily Quota

| Plan | Daily Quota | For | |------|------------|-----| | Free | Basic | Personal testing | | Plus | Higher | Small teams | | Max | High | Mid-size projects | | Neo | Highest | Large-scale |

Details on pricing. Quota resets daily.

Rate Limiting (Per Second)

Beyond daily totals, there's per-second concurrency to prevent burst overload. Exceeding returns 429 Too Many Requests:

{ "success": false, "error": "Rate limit exceeded. Retry after 60s." }

Developer Best Practices

Use Webhook Instead of Polling

Polling wastes quota — most queries return empty. Webhooks notify on arrival, saving quota.

Cache Results

const cache = new Map();
async function getMessage(id) {
  if (cache.has(id)) return cache.get(id);
  const res = await fetch(`/v1/messages/${id}`, { headers });
  const msg = await res.json();
  cache.set(id, msg);
  return msg;
}

Exponential Backoff

async function apiCallWithRetry(url, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, { headers });
    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, Math.pow(2, i) * 1000));
      continue;
    }
    return res.json();
  }
  throw new Error("Max retries exceeded");
}

FAQ

What if quota runs out? Wait for daily reset, or upgrade.

How to handle 429? Stop calling, wait for Retry-After header, implement exponential backoff.

Is free tier enough? For personal testing yes. Production CI needs paid plans.

Want API integration? See full docs, or read API getting started.