MailnapticSign inCreate an accountHelp CenterAPI docs

API Rate Limits

Understand API rate limiting and best practices

API Rate Limits

Mailnaptic enforces rate limits on all API endpoints to ensure fair usage and platform stability. Understanding these limits and designing your integration accordingly will help you avoid disruptions and build a reliable application.

Rate Limit Tiers

Rate limits are applied per API key and vary by endpoint category:

  • General endpoints (contacts, lists, segments, campaigns): 120 requests per minute
  • Bulk operations (CSV import, batch updates): 10 requests per minute
  • Authentication endpoints (login, token refresh): 30 requests per 5 minutes
  • AI-powered endpoints (content generation, subject scoring): 20 requests per minute
  • Search and reporting: 60 requests per minute

These limits are designed to accommodate typical integration patterns while protecting the platform from accidental or intentional overuse.

Rate Limit Headers

Every API response includes headers that tell you where you stand:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1710772800
  • X-RateLimit-Limit — the maximum number of requests allowed in the current window
  • X-RateLimit-Remaining — how many requests you have left in this window
  • X-RateLimit-Reset — Unix timestamp when the window resets

What Happens When You Hit the Limit

When you exceed the rate limit, Mailnaptic returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before trying again. The response body includes a JSON error message explaining the limit that was exceeded.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 42 seconds."
}

Best Practices for Staying Within Limits

  • Implement exponential backoff: When you receive a 429 response, wait for the duration specified in Retry-After, then retry. If subsequent requests also fail, double the wait time each attempt.
  • Use bulk endpoints: Instead of creating contacts one at a time, use the CSV import or batch endpoints to handle multiple records in a single request.
  • Cache responses: Store data that doesn't change frequently — such as custom field definitions, list metadata, or template content — and only refresh periodically.
  • Monitor your usage: Track the X-RateLimit-Remaining header in your application and throttle requests proactively before hitting the ceiling.
  • Spread requests over time: If you need to sync a large dataset, spread the requests evenly rather than sending them in bursts.
  • Use webhooks for real-time data: Instead of polling for campaign stats or contact changes, set up webhooks to receive push notifications when events occur.

Requesting Higher Limits

If your integration requires higher throughput, contact Mailnaptic support with details about your use case. We can evaluate and adjust limits for your organization on a case-by-case basis.

More in API & Developer