Troubleshooting

Start with these checks

docker compose ps
docker compose logs -f
curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/readyz

Connection refused on port 8000

Confirm the container is running and the published address matches the address you are calling. A loopback binding is available only from the same host. Inspect Compose status and logs, then check for a port conflict.

/readyz returns 503

Required configuration is missing or invalid. Inspect the logs and verify the API key length, SMTP host, port, security mode, envelope sender, and credentials in the container environment.

Invalid API key

Send the configured value in X-API-Key. Check for whitespace, shell interpolation, a stale secret, or a request going to a different environment.

Sender domain not allowed

Add the exact domain of the request-level from_email to ALLOWED_FROM_DOMAINS, using comma-separated values. Then recreate the service. Only add domains you control and your SMTP provider authorizes.

SMTP authentication failure

Verify username and password, whether the provider requires an app password, and whether SMTP access is enabled. Confirm SMTP_AUTH matches the relay’s requirements.

STARTTLS not advertised

The server and selected security mode disagree. Confirm host and port. Port 587 commonly uses starttls; port 465 commonly uses ssl. For a trusted local relay, use only the explicitly supported unencrypted mode.

Sender verification failed

The provider rejected the envelope or visible sender. Verify the domain or mailbox with the provider and ensure SMTP_FROM_EMAIL and request-level from_email follow its policy.

Message accepted but not received

Acceptance is not final delivery. Check provider logs, the recipient spam or quarantine folder, bounce messages for the envelope sender, and recipient-server deferrals. Avoid blind retries because the first message may still arrive.

Gmail spam-folder delivery

Check SPF, DKIM, DMARC alignment, sender reputation, message content, and complaint rates. Inbox placement is determined downstream and cannot be guaranteed by OwnSMTP.

SPF, DKIM, or DMARC failures

Use the DNS records and selectors issued by your SMTP provider, allow time for propagation, and verify alignment with the visible From domain. Avoid creating multiple SPF records for one hostname.

GHCR package pull denied

Confirm the image name and tag. If the package is public, stale local credentials can still interfere. Log out and pull the pinned image again:

docker logout ghcr.io
docker pull ghcr.io/samirkoirala/ownsmtp:1.1.2

Docker uses stale GHCR credentials

After docker logout ghcr.io, inspect your configured credential helper if the problem continues. Authenticate again only when the package requires it, using a token with the minimum necessary package permission.