Rate limits y cuotas

MailerDash aplica dos tipos de límites a los envíos: un límite de tasa por minuto (rate_per_min) y una cuota mensual (monthly_quota). Ambos se definen a nivel de plan (package) y pueden tener overrides por cuenta configurados por el equipo de MailerDash.

---

Límite de tasa (rate_per_min)

Controla cuántos requests de envío puede hacer tu API key en una ventana de 60 segundos. Si superas este límite, la API responde con HTTP 429.

El valor por defecto para cuentas sin plan asignado es de 30 requests/minuto. Tu plan puede otorgarte un límite mayor.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please slow down."
  }
}

La respuesta incluye los headers estándar de rate limit:

Header	Descripción
RateLimit-Limit	Límite máximo de requests en la ventana
RateLimit-Remaining	Requests restantes en la ventana actual
RateLimit-Reset	Timestamp Unix cuando se resetea la ventana

Consejo

Implementa un mecanismo de retry con backoff exponencial en tu integración para absorber picos de tráfico sin perder envíos. Al recibir un 429, espera al menos el tiempo indicado por RateLimit-Reset antes de reintentar.

---

Cuota mensual (monthly_quota)

Es el número máximo de correos que puedes enviar en un periodo de facturación (mes). El contador se resetea al inicio de cada nuevo periodo.

Cuando alcanzas la cuota mensual, los envíos adicionales son rechazados con HTTP 429:

{
  "error": {
    "type": "rate_limit_error",
    "code": "monthly_quota_exceeded",
    "message": "Monthly quota exceeded: 5000/5000 emails sent this month"
  }
}

Overage

Si tu plan lo contempla, puedes seguir enviando después de agotar tu cuota base pagando por correo adicional (overage). Si el plan no ofrece overage, los envíos que excedan la cuota serán bloqueados con el código overage_not_offered.

---

Consultar tu uso actual

GET /v1/client/usage
Authorization: Bearer $MAILERDASH_API_KEY

Este endpoint retorna el uso del periodo actual por cada API key vinculada a tu cuenta, junto con los límites del plan activo:

{
  "subscriptions": [
    {
      "package_id": "pro",
      "package_name": "Pro",
      "monthly_quota": 50000,
      "rate_per_min": 120,
      "billing_period": "monthly",
      "started_at": "2026-06-01T00:00:00.000Z"
    }
  ],
  "keys": [
    {
      "id": "mi-key",
      "label": "Producción",
      "sent_this_period": 12340,
      "monthly_quota": 50000,
      "quota_remaining": 37660
    }
  ],
  "next_reset": "2026-07-01T00:00:00.000Z"
}

El campo next_reset indica cuándo se reiniciará el contador mensual.

---

Historial por periodo

Para ver los periodos anteriores y no sólo el actual:

GET /v1/client/usage/history?periods=12
Authorization: Bearer $MAILERDASH_API_KEY

periods es cuántos periodos devolver (por defecto 12, máximo 36). Cada entrada trae el periodo, su fecha de inicio y cuántos correos salieron:

{
  "periods": [
    { "period": "bp:2026-07-19", "starts_at": "2026-07-19", "sent": 41230 },
    { "period": "bp:2026-08-19", "starts_at": "2026-08-19", "sent": 52104 }
  ]
}

Los periodos son de facturación, no meses calendario: tu cuota se resetea el día que compraste el plan, no el día 1, y el historial respeta eso — es lo que vives cuando te avisamos que estás cerca del límite. Por eso starts_at es lo que hay que usar para ordenar o para el eje de una gráfica; el period es el identificador interno y no ordena alfabéticamente entre formatos.

Un reset de cuota no borra el periodo anterior: abre uno nuevo. El historial es acumulativo desde que tu cuenta existe, acotado a los últimos periods.

Rampa del remitente nuevo

Si tu cuenta es nueva, además del límite de tu plan aplica un tope diario que crece solo. Empieza en 200 correos el primer día y sube ~25% cada día hasta graduarse al cabo de 30 días.

Día	Tope diario aproximado
1	200
7	763
15	5.684
30	sin rampa — manda el tope de tu plan

El reloj arranca con tu primer envío, no con el alta de la cuenta: una cuenta creada hace meses que nunca envió y de pronto arranca con volumen es justo el perfil que esto cuida.

Siempre se aplica el menor entre la rampa y el tope de tu plan. Un plan más caro no salta la rampa —la reputación compartida no se compra— pero tampoco te sube por encima de lo que contrataste.

Al superar el tope del día recibes un 429:

{
  "error": {
    "type": "rate_limit_error",
    "code": "daily_cap_exceeded",
    "message": "Daily cap exceeded: 200/200"
  }
}

Nota

Esto existe porque enviamos desde IP compartida. El riesgo no es una IP fría —la nuestra ya tiene historia— sino una cuenta nueva que estrena mandando 50.000 correos a una lista comprada. Para cuando eso se detecta por rebotes y quejas, el daño a la reputación de todos ya está hecho.

---

Límites de payload

• Tamaño por adjunto: 25 MB.
• Total de adjuntos por envío: 25 MB.
• Cuerpo del request: 35 MB en /v1/mail/send. Es más alto que el resto de la API justamente para que quepan esos 25 MB una vez codificados en base64, que infla el tamaño ~33%.

Al excederlos recibes un 413 con código payload_too_large.

Consejo

Ten en cuenta que Gmail y Outlook rechazan mensajes de más de 25 MB, así que un adjunto que apure ese límite puede ser aceptado por nosotros y rebotar en el destino. Para archivos grandes conviene enlazar en vez de adjuntar.

---

Resumen de códigos de error relacionados

code	HTTP	Descripción
rate_limit_exceeded	429	Superaste el límite de requests por minuto
monthly_quota_exceeded	429	Superaste la cuota mensual de tu plan
daily_cap_exceeded	429	Superaste el tope diario de la rampa del remitente nuevo
overage_not_offered	400	El plan no permite envíos extra tras agotar la cuota
payload_too_large	413	El body del request excede el tamaño máximo

Ver la referencia completa en /reference/platform/ y el manejo de errores en /referencia/errores/.