Troubleshooting

A growing list of the most common gotchas.

Email isn't being delivered

Check Settings → Email logs. If the message is bounced, the recipient is rejecting it (often non-existent address).
Verify your domain DNS records are all green under Settings → Domains → <domain>. Especially DKIM — without it most inboxes will spam you.
Run mail-tester.com against an address on your domain. Aim for 9–10/10.
New domain? Check Settings → Warmup — you may be capped at 50/day right now.

"rate limit exceeded" (HTTP 429)

You hit the per-IP (300/min) or per-key (60/min) limit. Back off with exponential retry. Get in touch if you need higher.

"invalid or revoked api key" (HTTP 401)

Did you copy the full key including the kx_ prefix?
Did someone revoke it in Settings → API Keys?
Are you using the right environment's key (test vs production)?

Worker keeps retrying `ai:classify`

Older AI tasks may reference body_text (renamed to text_body long ago). The fix already shipped — restart the worker:

docker compose restart worker

SMTP relay rejects MAIL FROM

The SMTP relay parses standard MAIL FROM:<addr> with extensions. Make sure your client wraps the address in angle brackets. Most libraries do this for you; if you're constructing the protocol manually:

MAIL FROM:<[email protected]> SIZE=571

"warmup quota exceeded"

Your domain is still in its first weeks. Either wait until tomorrow (counter resets at midnight server time) or pause warmup in Settings → Warmup once you trust the domain (not recommended for the first week).

Logs

docker compose logs -f api
docker compose logs -f worker
docker compose logs -f smtp

Reset onboarding state for testing

UPDATE public.tenants SET onboarding_state = '{}'::jsonb;