Rate limits and quotas

MailerDash enforces two types of limits on sends: a per-minute rate limit (rate_per_min) and a monthly quota (monthly_quota). Both are defined at the plan (package) level and can have per-account overrides configured by the MailerDash team.

---

Rate limit (rate_per_min)

Controls how many send requests your API key can make within a 60-second window. If you exceed this limit, the API responds with HTTP 429.

The default for accounts without an assigned plan is 30 requests/minute. Your plan may grant a higher limit.

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

The response includes the standard rate limit headers:

Header	Description
RateLimit-Limit	Maximum number of requests in the window
RateLimit-Remaining	Requests remaining in the current window
RateLimit-Reset	Unix timestamp when the window resets

Tip

Implement a retry mechanism with exponential backoff in your integration to absorb traffic spikes without losing sends. When you receive a 429, wait at least until the time indicated by RateLimit-Reset before retrying.

---

Monthly quota (monthly_quota)

The maximum number of emails you can send in a billing period (month). The counter resets at the start of each new period.

When you reach your monthly quota, additional sends are rejected with HTTP 429:

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

Overage

If your plan includes it, you can continue sending after exhausting your base quota by paying per additional email (overage). If the plan does not offer overage, sends that exceed the quota will be blocked with the code overage_not_offered.

---

Check your current usage

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

This endpoint returns the usage for the current period for each API key linked to your account, along with the limits of the active plan:

{
  "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"
}

The next_reset field indicates when the monthly counter will reset.

---

History by period

To see previous periods and not just the current one:

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

periods is how many periods to return (12 by default, 36 max). Each entry carries the period, its start date and how many emails went out:

{
  "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 }
  ]
}

Periods are billing periods, not calendar months: your quota resets on the day you bought the plan, not on the 1st, and the history honours that — it’s what you actually live when we warn you that you’re close to the limit. That’s why starts_at is what you should sort by, or use as a chart axis; period is the internal identifier and does not sort alphabetically across formats.

A quota reset does not erase the previous period: it opens a new one. The history is cumulative since your account existed, capped to the last periods.

New sender ramp-up

If your account is new, a daily cap that grows on its own applies on top of your plan’s limit. It starts at 200 emails on day one and rises ~25% per day until it graduates after 30 days.

Day	Approximate daily cap
1	200
7	763
15	5,684
30	no ramp — your plan’s cap applies

The clock starts with your first send, not when the account was created: an account made months ago that never sent and suddenly starts at volume is exactly the profile this guards against.

The lower of the ramp and your plan’s cap always wins. A pricier plan doesn’t skip the ramp — shared reputation isn’t for sale — but it won’t raise you above what you signed up for either.

Going over the day’s cap returns a 429:

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

Note

This exists because we send from a shared IP. The risk isn’t a cold IP — ours has history — but a brand-new account starting off with 50,000 emails to a purchased list. By the time that shows up in bounces and complaints, the damage to everyone’s reputation is already done.

---

Payload limits

• Per attachment: 25 MB.
• Total attachments per send: 25 MB.
• Request body: 35 MB on /v1/mail/send. It’s higher than the rest of the API precisely so those 25 MB fit once base64-encoded, which inflates size by ~33%.

Exceeding them returns a 413 with code payload_too_large.

Tip

Keep in mind Gmail and Outlook reject messages over 25 MB, so an attachment that pushes that limit may be accepted by us and bounce at the destination. For large files, link instead of attaching.

---

Summary of related error codes

code	HTTP	Description
rate_limit_exceeded	429	You exceeded the per-minute request limit
monthly_quota_exceeded	429	You exceeded your plan’s monthly quota
daily_cap_exceeded	429	You exceeded the daily cap of the new sender ramp-up
overage_not_offered	400	The plan does not allow extra sends after the quota is exhausted
payload_too_large	413	The request body exceeds the maximum size

See the full reference at /reference/platform/ and error handling at /en/reference/errors/.