Troubleshooting

Troubleshooting

SMTP relay connection refused

Check that the relay is enabled and Docker publishes port 2525:

docker compose ps
docker logs mail-bridge

SMTP relay connection denied

Compare the logged remote address with SMTP_RELAY_ALLOWED_CIDRS. Docker Desktop may present the host as an address such as 192.168.65.1; Linux Docker commonly uses a different bridge range. Add only the narrow network actually required.

Relay fails at startup because TLS files are missing

The relay fails closed when STARTTLS is required without both SMTP_RELAY_TLS_CERT_FILE and SMTP_RELAY_TLS_KEY_FILE. Supply the mounted certificate paths or explicitly select insecure compatibility mode for a trusted isolated network.

Outbound Cloudflare request receives 403

Confirm the Worker secret CLOUDFLARE_SEND_WEBHOOK_SECRET matches the value used by Mailbridge. Current releases prefer this dedicated outbound secret and fall back to WEBHOOK_SECRET only when it is absent.

getaddrinfo ENOTFOUND

The container cannot resolve CLOUDFLARE_SEND_WORKER_URL. Use the deployed workers.dev endpoint until custom DNS resolves correctly.

Missing env.EMAIL

Ensure wrangler.toml contains:

[[send_email]]
name = "EMAIL"

It must be top-level.

Spam filter unavailable

For local mode, confirm spamd starts and listens on the configured host/port. For Postmark mode, verify POSTMARK_SPAMCHECK_URL and outbound connectivity. Mailbridge rejects inbound mail when all configured filtering is unavailable unless fail-open was explicitly enabled.

SpamAssassin DNSBL warnings

Rules such as RCVD_IN_DNSWL_BLOCKED, URIBL_BLOCKED, or RCVD_IN_ZEN_BLOCKED_OPENDNS generally mean a DNSBL provider is limiting the configured resolver. SpamAssassin can still return a score, but consider a suitable resolver, disabling affected rules, Postmark SpamCheck mode, or explicitly configured Spamhaus checks.

Spamhaus enabled without credentials

Set both SPAMHAUS_USERNAME and SPAMHAUS_PASSWORD, or return SPAMHAUS_ENABLED to false. Do not leave the feature partially configured.

Local SMTP TLS name warning or failure

When LOCAL_MAIL_HOST is an IP address, set LOCAL_MAIL_TLS_SERVERNAME to the DNS name on the server certificate. Use LOCAL_MAIL_TLS_CA_FILE for a private CA rather than disabling certificate verification.