Rate Limiting

Rate Limiting

Comprehensive rate limiting protects your forms and API endpoints from abuse while ensuring legitimate users have smooth access.

Overview

mailiam implements multiple layers of rate limiting:

1. Per-IP Rate Limiting - Limits submissions per IP address
2. Per-Form Rate Limiting - Limits submissions per form
3. Global Rate Limiting - Account-wide submission limits
4. API Rate Limiting - Limits API requests per API key

Per-IP Rate Limiting

Default Configuration

By default, mailiam applies these per-IP limits:

settings:
  rate_limit: 10  # 10 submissions per hour per IP address

Form-Specific IP Limits

Configure different limits per form:

domains:
  yourdomain.com:
    forms:
      contact:
        name: "Contact Form"
        rateLimit: 5           # 5 submissions per hour per IP

      newsletter:
        name: "Newsletter Signup"
        rateLimit: 2           # 2 signups per hour per IP

      support:
        name: "Support Form"
        rateLimit: 3           # 3 support requests per hour per IP

Advanced IP Rate Limiting

Configure granular IP-based limits:

forms:
  contact:
    rate_limiting:
      per_ip:
        hourly: 10              # 10 per hour
        daily: 50               # 50 per day
        weekly: 200             # 200 per week

      # Different limits for different IP ranges
      ip_ranges:
        "192.168.1.0/24":       # Internal network
          hourly: 100
          daily: 1000

        "203.0.113.0/24":       # Partner network
          hourly: 25
          daily: 200

Per-Form Rate Limiting

Basic Form Limits

Limit total submissions per form regardless of IP:

forms:
  contact:
    rate_limiting:
      total_submissions:
        per_minute: 20          # Max 20 submissions per minute
        per_hour: 100           # Max 100 submissions per hour
        per_day: 500           # Max 500 submissions per day

Burst Protection

Handle traffic spikes while maintaining limits:

forms:
  contact:
    rate_limiting:
      burst:
        enabled: true
        capacity: 50            # Allow 50 rapid submissions
        refill_rate: 10         # Refill 10 tokens per minute
        recovery_time: 300      # 5 minutes to full recovery

Time-Based Rate Limiting

Business Hours Limits

Different limits during business hours vs. off-hours:

forms:
  contact:
    rate_limiting:
      time_based:
        timezone: "America/New_York"

        business_hours:
          hours: "09:00-17:00"
          days: ["monday", "tuesday", "wednesday", "thursday", "friday"]
          per_ip_hourly: 15
          total_hourly: 200

        off_hours:
          per_ip_hourly: 5
          total_hourly: 50

Progressive Limiting

Stricter limits during high-traffic periods:

forms:
  newsletter:
    rate_limiting:
      progressive:
        thresholds:
          - submissions: 100     # After 100 submissions in hour
            per_ip_limit: 1      # Reduce to 1 per IP per hour

          - submissions: 500     # After 500 submissions in hour
            per_ip_limit: 0      # Block new IPs entirely
            existing_ip_limit: 1  # Existing IPs get 1 more

Global Rate Limiting

Account-Wide Limits

Configure limits for your entire mailiam account:

settings:
  global_limits:
    hourly: 1000               # 1000 submissions per hour across all forms
    daily: 10000               # 10000 submissions per day
    monthly: 100000            # 100000 submissions per month

    api_requests:
      per_minute: 100          # 100 API requests per minute
      per_hour: 5000           # 5000 API requests per hour

Plan-Based Limits

Limits automatically adjust based on your mailiam plan:

Plan	Email Quota	Hourly Form Limit	Daily Form Limit
Free	180/month (360 first month)	100	1,000
Pro	10,000/month + overage	2,000	20,000
Enterprise	Custom	Custom	Custom

API Rate Limiting

API Key Limits

Different limits based on API key permissions:

# Set via CLI or API
api_keys:
  production:
    rate_limits:
      requests_per_minute: 100
      requests_per_hour: 5000
      burst_capacity: 200

  development:
    rate_limits:
      requests_per_minute: 50
      requests_per_hour: 1000
      burst_capacity: 100

Endpoint-Specific Limits

Different limits for different API endpoints:

Endpoint	Requests/Minute	Requests/Hour
/forms/{id}/submit	60	3,600
/instant/forms	20	1,000
/domains/verify	10	100
/collections/{id}	30	1,500

Rate Limit Headers

mailiam returns rate limit information in response headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1609459200
X-RateLimit-RetryAfter: 3600

Header Definitions

• X-RateLimit-Limit: Maximum requests allowed in time window
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when limit resets
• X-RateLimit-RetryAfter: Seconds until you can retry (when limited)

Rate Limit Responses

HTTP 429 - Too Many Requests

When rate limited, mailiam returns:

{
  "error": "Rate limit exceeded",
  "message": "Too many submissions from this IP address",
  "retry_after": 3600,
  "limit": 10,
  "remaining": 0,
  "reset_time": "2024-01-01T12:00:00Z"
}

Custom Rate Limit Messages

Configure custom messages for rate limit responses:

forms:
  contact:
    rate_limiting:
      messages:
        ip_limited: "You've submitted too many forms. Please wait an hour and try again."
        form_limited: "This form is temporarily unavailable due to high traffic."
        global_limited: "Our service is experiencing high load. Please try again later."

Monitoring Rate Limits

CLI Monitoring

Check rate limit status via CLI:

# Check current rate limit status
mailiam domains status --rate-limits

# View rate limit history
mailiam instant submissions form_abc123 --rate-limit-data

# Monitor real-time rate limiting
mailiam monitor rate-limits --live

Rate Limit Analytics

View detailed rate limiting analytics:

# Generate rate limit report
mailiam analytics rate-limits --last-24h

# Export rate limit data
mailiam analytics export --type rate-limits --format csv

Example output:

Rate Limit Report - Last 24 Hours
================================

Contact Form (form_abc123):
  Total submissions: 245
  Rate limited: 23 (9.4%)
  Peak hour: 14:00-15:00 (67 submissions)

IP Rate Limiting:
  Unique IPs: 156
  IPs rate limited: 12
  Top limited IP: 203.0.113.44 (8 attempts over limit)

Form Rate Limiting:
  Burst events: 3
  Peak minute: 14:23 (34 submissions)

Advanced Configuration

Dynamic Rate Limiting

Adjust limits based on traffic patterns:

forms:
  contact:
    rate_limiting:
      adaptive:
        enabled: true
        base_limit: 10          # Base limit per IP per hour

        scaling:
          low_traffic:          # < 50 submissions/hour
            multiplier: 1.5     # Increase to 15 per IP

          normal_traffic:       # 50-200 submissions/hour
            multiplier: 1.0     # Keep at 10 per IP

          high_traffic:         # > 200 submissions/hour
            multiplier: 0.5     # Reduce to 5 per IP

Geographic Rate Limiting

Different limits based on geographic location:

forms:
  contact:
    rate_limiting:
      geographic:
        default: 10             # Default limit

        countries:
          US: 15               # Higher limit for US
          CA: 15               # Higher limit for Canada
          GB: 12               # Slightly higher for UK

          CN: 2                # Lower limit for China
          RU: 2                # Lower limit for Russia

        continents:
          EU: 12               # European Union default
          AS: 5                # Asia default (lower)

Content-Based Rate Limiting

Adjust limits based on submission content:

forms:
  contact:
    rate_limiting:
      content_based:
        url_detection:
          no_urls: 10           # Normal limit if no URLs
          has_urls: 3           # Reduced limit if URLs present
          multiple_urls: 1      # Very low if multiple URLs

        message_length:
          short: 10             # < 100 characters
          medium: 8             # 100-500 characters
          long: 5               # > 500 characters

Exemptions and Whitelisting

IP Whitelisting

Exempt specific IPs from rate limiting:

forms:
  contact:
    rate_limiting:
      whitelist:
        ips:
          - "192.168.1.0/24"    # Internal network
          - "203.0.113.10"      # Specific trusted IP
          - "2001:db8::/32"     # IPv6 range

        # Trusted user agents
        user_agents:
          - "MyApp/1.0"
          - "TrustedBot/2.1"

API Key Exemptions

Higher limits for specific API keys:

api_keys:
  partner_key:
    rate_limits:
      exempt: true              # No rate limiting

  premium_key:
    rate_limits:
      multiplier: 10            # 10x normal limits

Time-Based Exemptions

Temporarily disable rate limiting:

# Disable rate limiting for 1 hour during traffic spike
mailiam rate-limits disable --form contact --duration 1h

# Schedule exemption for known high-traffic event
mailiam rate-limits schedule --form newsletter \
  --start "2024-01-01T09:00:00Z" \
  --end "2024-01-01T18:00:00Z" \
  --multiplier 5

Testing Rate Limits

Manual Testing

Test rate limits with curl:

# Test IP rate limiting
for i in {1..15}; do
  echo "Request $i:"
  curl -X POST https://api.mailiam.dev/yourdomain.com/contact \
    -F "name=Test $i" \
    -F "email=test$i@example.com" \
    -F "message=Test message $i" \
    -w "Status: %{http_code}\n"
  sleep 1
done

Load Testing

Use load testing tools to verify rate limits:

# Using Apache Bench
ab -n 100 -c 10 -p form-data.txt -T application/x-www-form-urlencoded \
  https://api.mailiam.dev/yourdomain.com/contact

# Using curl with parallel requests
seq 1 50 | xargs -n1 -P10 -I{} curl -X POST \
  https://api.mailiam.dev/yourdomain.com/contact \
  -F "name=Load Test {}" \
  -F "email=loadtest{}@example.com" \
  -F "message=Load test message {}"

CLI Testing

Use mailiam CLI for testing:

# Test rate limits for specific form
mailiam test rate-limits --form contact --requests 20

# Simulate burst traffic
mailiam test rate-limits --form contact --burst --duration 60s

# Test with different IP addresses (if using proxy)
mailiam test rate-limits --form contact --vary-ip

Best Practices

1. Start Conservative

Begin with stricter limits and relax as needed:

# Initial conservative settings
forms:
  contact:
    rateLimit: 5              # Start low

# Monitor for 1-2 weeks, then adjust:
forms:
  contact:
    rateLimit: 10             # Increase based on legitimate traffic

2. Monitor Regularly

Set up regular monitoring:

# Weekly rate limit review
mailiam analytics rate-limits --weekly

# Set up alerts for high rate limiting
mailiam alerts create --type rate-limit-exceeded --threshold 50%

3. Provide Clear Feedback

Help users understand rate limits:

forms:
  contact:
    rate_limiting:
      messages:
        ip_limited: |
          You've reached the maximum number of submissions for this hour.
          Please wait 60 minutes or contact us directly at hello@company.com
          if this is urgent.

4. Plan for Traffic Spikes

Prepare for expected high-traffic events:

forms:
  product_launch:
    rate_limiting:
      scheduled_adjustments:
        - start: "2024-01-15T09:00:00Z"
          end: "2024-01-15T18:00:00Z"
          per_ip_hourly: 50      # 5x normal limit during launch

5. Balance Security and Usability

Find the right balance:

• Too strict: Legitimate users blocked
• Too loose: Vulnerable to abuse
• Monitor false positive rates
• Adjust based on user feedback

Troubleshooting

Common Issues

Legitimate Users Being Rate Limited

Symptoms: Support requests about blocked forms

Solutions:

1. Check if limits are too restrictive
2. Verify IP whitelisting for known users
3. Consider increasing limits during business hours
4. Implement progressive limiting instead of hard stops

Rate Limits Not Working

Symptoms: Spam getting through despite limits

Solutions:

1. Verify rate limiting is enabled
2. Check configuration syntax
3. Ensure limits are appropriate for threat level
4. Consider additional security measures

Performance Issues

Symptoms: Slow form submissions due to rate limit processing

Solutions:

1. Optimize rate limit checking
2. Use Redis for faster lookups (enterprise)
3. Implement efficient IP range checking
4. Consider CDN-based rate limiting

Debugging Commands

# Check rate limit configuration
mailiam test config --check-rate-limits

# Debug specific rate limit issue
mailiam debug rate-limits --ip 203.0.113.44 --form contact

# View rate limit logs
mailiam logs rate-limits --last-hour --form contact

Getting Help

Documentation

• Security Overview - General security practices
• Anti-Spam Protection - Comprehensive spam protection
• Configuration Schema - Complete configuration reference

Support Resources

1. Rate Limit Calculator: Online tool to estimate appropriate limits
2. Best Practices Guide: Industry-specific recommendations
3. Community Forum: Discuss rate limiting strategies
4. Enterprise Support: Custom rate limiting solutions

Support Request Information

When requesting help with rate limiting, include:

• Current rate limit configuration
• Traffic patterns (peak times, volumes)
• Legitimate vs. spam traffic ratios
• Specific issues you’re experiencing
• Business requirements and constraints

Rate limiting is crucial for maintaining service quality while preventing abuse. Start with conservative settings and adjust based on your traffic patterns and security needs.