Limites de débit

Mailbeam applique deux types de limites : des quotas mensuels (par forfait) et des limites de débit par seconde (par clé d'API).

Mailbeam est uniquement payant. Les requêtes en production d'un compte sans forfait payant actif renvoient un 402 avec error: "plan_required" ; le compte, ses clés et son historique sont conservés. Les clés de test fonctionnent sur tous les comptes, renvoient des résultats simulés et ne comptent jamais dans le quota.

Quotas mensuels

Chaque forfait comprend un nombre fixe de vérifications par mois calendaire :

ForfaitVérifications par mois
Mini1 000
Starter5 000
Growth25 000
Pro100 000
Scale500 000
EnterpriseSur mesure

Votre quota se remet à zéro à minuit UTC, à la date anniversaire de votre facturation. Vous pouvez consulter votre consommation actuelle sur /v1/account/usage.

Limites de débit par seconde

ForfaitRequêtes par seconde
Mini5
Starter10
Growth25
Pro50
Scale200
EnterpriseSur mesure

Une requête sur l'endpoint batch compte pour une requête par envoi de lot, pas pour une par adresse du lot.

En-têtes de limite de débit

Chaque réponse porte des en-têtes qui indiquent l'état courant de vos limites :

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1716825600
X-Quota-Limit: 50000
X-Quota-Remaining: 43218
X-Quota-Reset: 1719532800
En-têteDescription
X-RateLimit-LimitNombre maximum de requêtes par seconde pour votre forfait
X-RateLimit-RemainingRequêtes restantes dans la seconde en cours
X-RateLimit-ResetHorodatage Unix de la remise à zéro de la fenêtre à la seconde
X-Quota-LimitQuota mensuel de vérifications
X-Quota-RemainingVérifications restantes ce mois-ci
X-Quota-ResetHorodatage Unix de la remise à zéro du quota mensuel

Traiter les réponses 429

Quand vous dépassez la limite de débit par seconde, vous recevez une réponse 429 Too Many Requests :

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "retry_after": 1
}

Le champ retry_after indique le nombre de secondes à attendre avant de réessayer.

Stratégie de backoff conseillée

Employez un backoff exponentiel avec gigue pour un traitement robuste des limites :

async function verifyWithRetry(email, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await verifyEmail(email);
    } catch (err) {
      if (err.status === 429 && attempt < maxRetries - 1) {
        const retryAfter = err.retryAfter ?? 1;
        const jitter = Math.random() * 1000; // 0–1000 ms
        const delay = retryAfter * 1000 * Math.pow(2, attempt) + jitter;
        await new Promise((r) => setTimeout(r, delay));
      } else {
        throw err;
      }
    }
  }
}

Pour une vérification en masse, passez par l'endpoint batch plutôt que d'enchaîner des requêtes individuelles dans une boucle. L'endpoint batch gère lui-même la concurrence de notre côté.

Quota épuisé

Quand votre quota mensuel est épuisé, tous les forfaits payants continuent de répondre et facturent les vérifications supplémentaires en dépassement : vous n'êtes pas bloqué. Un forfait sans facturation du dépassement répondrait à la place un 429 avec error: "quota_exceeded". Sans forfait payant actif, les requêtes en production renvoient un 402 avec error: "plan_required" jusqu'à ce que vous choisissiez un forfait.

Vous recevez un e-mail de notification quand vous atteignez 80 % puis 100 % de votre quota mensuel.