Docs › Troubleshooting & FAQ

Troubleshooting & FAQ

Fixes for the things people hit most.

My emails go to spam

Almost always authentication or reputation:

Verify your domain so SPF + DKIM pass, and add a DMARC record. See Verify a sending domain.
Send from a subdomain, keep transactional and bulk on separate streams, and warm up new domains gradually. See Deliverability.
Check your bounce/complaint rates in Activity. High rates tank placement.

Domain won't verify

DNS records must match exactly. Common causes: the host/name got the domain double-appended, the root needs @, or DNS hasn't propagated yet (wait, then re-verify). See Verify a sending domain.

We emailed you that DNS records are missing

We re-check every verified domain several times a day. If its DKIM or return-path records disappear from DNS (often after moving DNS provider or tidying up records), we email the account owner the exact records to restore and show a warning on the domain.

DKIM missing: publish it again within about 3 days. After that the domain is no longer verified and sending from it stops until the record is back.
Return-path missing: sending carries on, but bounces no longer come back through your domain and SPF stops lining up with it, which hurts inbox placement.

Publish the records marked Missing on the domain page, then press Re-check DNS. Sending picks up as soon as they check out. See Verify a sending domain.

`403` when sending

Two usual reasons: the `from` domain isn't verified, or your account's sending isn't approved yet (new accounts pass an approval step before live sending). Verify the domain and check the approval banner in the dashboard.

`401 Unauthorized`

The API key is missing, malformed, or revoked. Send it as Authorization: Bearer <key>, and confirm the key belongs to the right project. See API keys.

`422` validation error

The response names the bad field. Common ones: from must be Name <address> form, to must be a non-empty array of valid addresses, and you need subject + a body (html/text) unless you use a template.

I sent twice / duplicate emails

Add an idempotencyKey to each send so a retry returns the original result instead of sending again. See Send email via the API.

A recipient isn't getting mail

Check Activity for that message. If it shows suppressed, the address is on your suppression list (a prior bounce, complaint, or unsubscribe). Only remove it if you're sure it's deliverable and wanted.

Webhooks aren't arriving

Confirm the endpoint is public HTTPS and returns 2xx quickly; check recent delivery attempts on the Webhooks page. Handlers must be idempotent. Events can be retried. See Webhooks.

SMTP: can't log in, or mail is refused

`535` authentication failed: the username must be the credential's username (its first 12 characters) and the password the full credential. An ordinary API key cannot log in; create an SMTP credential instead.
`538` Must issue a STARTTLS command first: turn on encryption (STARTTLS on 587, or TLS on 465). Login is refused on an unencrypted connection.
`421` or `454` too many failed logins: repeated wrong passwords from one address lock it out for 15 minutes. Fix the setting, then wait.
`550 5.7.1`: the From address isn't on a verified domain or sender, or sending is paused or not yet approved. The same rules as the API apply.

See Send email over SMTP for every reply code.

Still stuck?

Email support@mailhuset.com with your project name and, for a specific email, its message id.

Need help? Email support@mailhuset.com.