Pagination and rate limits

Pagination

Most list endpoints return a counting paginator: items in data, page URLs in links, and counts in meta.

{
  "data": [],
  "links": {
    "first": "https://...",
    "last": "https://...",
    "prev": null,
    "next": "https://..."
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "per_page": 20,
    "to": 20,
    "total": 200,
    "path": "https://..."
  }
}

Two endpoints use a different shape:

• GET /v1/inboxes/{inbox_id}/tags uses a simple paginator that does not count the full result set. Its meta omits last_page and total, and adds current_page_url. Follow links.next until it is null instead of counting pages.
• POST /v1/search wraps the paginator in { success, data: { conversations: <paginator> } }.

Query parameters

Rate limits

Every API request first passes a global limiter, and a few sensitive routes add a stricter limiter. All limiters are keyed by client IP rather than access token, so a high-traffic single host can hit the limit even when using multiple valid tokens.

How a throttled request looks

HTTP/1.1 429 Too Many Requests
Retry-After: 47
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
Content-Type: application/json

{
  "message": "Too Many Attempts."
}

Back off using the Retry-After header, do not hammer the endpoint, and consider queueing requests client-side when you would otherwise approach the limit.

Configuring limits

Each limiter reads its max_attempts and decay_minutes from environment variables, defaulting to the values above:

API_RATE_LIMIT_GLOBAL=300,1
API_RATE_LIMIT_REGISTER=10,1
API_RATE_LIMIT_EMAIL_VERIFICATION=5,1

Related

• Idempotency and safe retries
• Errors