Limits & Quotas

This page documents all rate limits, payload limits, and quotas in FormaMail. We believe in transparency - knowing your limits before you hit them.

API Rate Limits

Rate limits protect the platform and ensure fair usage. Limits are applied per API key.

Email Endpoints

Template Endpoints

Analytics Endpoints

Webhook Subscription Endpoints

Rate Limit Headers

Every API response includes rate limit headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 25
X-RateLimit-Reset: 1732723200

Rate Limit Exceeded Response

When you exceed the rate limit:

{
  "statusCode": 429,
  "code": "ERR_QUOTA_001",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "retryAfter": 45
}

Best Practice: Implement exponential backoff when you receive a 429 response.

Payload Limits

Request Limits

Email Limits

Bulk Send Limits

Attachment Generation Limits

FormaMail enforces “Safe Harbor” limits on attachment generation to protect system resources and ensure reliable email delivery via AWS SES.

PDF Limits

Excel Limits

Template Processing Limits

Limit Violation Errors

When you exceed attachment limits, FormaMail immediately stops processing and returns a 400 Bad Request with a specific error code:

Example Error Response

{
  "statusCode": 400,
  "code": "ERR_LIMIT_001",
  "message": "PDF generation exceeded maximum page limit",
  "timestamp": "2025-12-09T10:30:00.000Z",
  "path": "/api/attachments/generate",
  "relatedInfo": {
    "actualPages": 45,
    "maxPages": 30,
    "message": "PDF generation exceeded 30 page limit. Your PDF has 45 pages."
  }
}

How to Handle Limit Errors

1. Split large datasets: Break data into multiple attachments
2. Paginate loops: Use pagination for arrays over 1,000 items
3. Optimize images: Compress images before including in PDFs
4. Simplify templates: Reduce nesting and component count

Template Limits

Content Limits

Template Counts by Plan

Account Quotas

Email Quotas by Plan

Credit System

FormaMail uses a credit-based system:

• 1 email = 1 credit
• 1 PDF attachment = 1 credit
• 1 Excel attachment = 1 credit

Example: Sending an email with a PDF attachment uses 2 credits.

Team Limits

API Key Limits

Webhook Limits

Subscription Limits

Delivery Limits

OAuth Limits

Token Limits

OAuth App Limits

Storage Limits

Asset Storage

Generated File Retention

Requesting Limit Increases

If you need higher limits, you have options:

Upgrade Your Plan

Higher plans come with increased limits. See Pricing.

Enterprise Custom Limits

Enterprise customers can request custom limits:

• Dedicated infrastructure
• Custom rate limits
• Higher storage quotas
• Dedicated IP addresses

Contact sales@formamail.com

Temporary Increases

For one-time events (product launches, campaigns), request a temporary limit increase:

Email: support@formamail.com

Include:

• Account/Team ID
• Requested limit increase
• Duration needed
• Use case description

Monitoring Your Usage

Dashboard

View your current usage in the dashboard:

• Overview: Current email/credit usage
• Settings → Usage: Detailed usage breakdown
• Settings → API Keys: Per-key usage statistics

API

Query usage programmatically:

GET /api/emails/usage/stats

Response:

{
  "period": "2024-11",
  "emailsSent": 15420,
  "creditsUsed": 18500,
  "creditsRemaining": 31500,
  "quota": 50000
}

Alerts

Set up usage alerts in Settings → Notifications:

• 50% quota usage
• 80% quota usage
• 100% quota usage
• Rate limit warnings

Best Practices

Avoid Rate Limits

1. Batch operations: Use bulk endpoints instead of multiple single requests
2. Cache responses: Don’t re-fetch unchanged data
3. Implement backoff: Exponential backoff on 429 responses
4. Use webhooks: Don’t poll for status updates

Optimize Payload Size

1. Compress images: Before including in templates
2. Limit data: Only include necessary variables
3. Paginate queries: Use pagination for large datasets

Handle Limits Gracefully

async function sendWithRetry(payload, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch('/api/emails/send', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${API_KEY}` },
      body: JSON.stringify(payload)
    });
 
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await sleep(retryAfter * 1000);
      continue;
    }
 
    return response.json();
  }
  throw new Error('Max retries exceeded');
}