Rate Limits

API Rate Limits

EmBoux currently does not enforce rate limiting at the API level. The API is designed for infrastructure provisioning, not high-frequency access patterns.

Typical usage patterns:

Operation	Expected Frequency
Create domain	Once per customer onboarding
Create mailbox	A few per domain setup
Create alias	A few per mailbox
Quota updates	On plan change
Suspend/activate	On payment events

SMTP Sending Limits

Outbound email is controlled at three time scales, enforced in real time by the Policy Daemon:

Hourly Throttle

Each domain can send at most ~1/6 of its daily limit per hour (minimum 10). This prevents burning the entire daily quota in a burst, which providers flag as spam.

Daily Limit	Hourly Cap
200	33
1,000	167
5,000	835
10,000	1,670

The fraction is configurable via HOURLY_FRACTION (default: 0.167).

Daily & Monthly Limits

Per-domain daily and monthly limits are set from the customer’s plan. See Outbound Email for details.

Spike Detection

If today’s sending volume exceeds 5x the 7-day rolling average, the domain is blocked (hard enforcement) or warned (soft enforcement). This protects against a well-behaved client suddenly sending mass email.

The multiplier is configurable per domain via spike_max_multiplier (0 = disabled).

Warm-up

New domains start with a progressive daily cap. See Warm-up Profiles for details.

Recommendations

1. Don’t poll — Use webhooks or Odoo crons for sync, not polling loops
2. Batch where possible — If creating multiple resources, do them sequentially without artificial delays
3. Set reasonable timeouts — We recommend 10-15 seconds per request
4. Handle errors gracefully — Retry 500 errors with exponential backoff (1s, 2s, 4s)
5. Spread sends over time — Don’t queue thousands of emails to fire simultaneously

Future API Rate Limits

When API-level rate limiting is introduced, it will follow standard HTTP conventions:

• 429 Too Many Requests status code
• Retry-After header with seconds to wait
• Per-key limits based on plan tier

We’ll announce changes with at least 30 days notice.

WAF Protection

The API sits behind a Web Application Firewall. To avoid being blocked:

• Set a proper User-Agent header (e.g., MyApp/1.0 or Odoo/19.0 (EmBoux Core Sync))
• Don’t send malformed or extremely large payloads
• Don’t make requests from known-bad IP ranges