Troubleshooting

Start in the console. Every mail carries its current state, every send attempt with the provider’s verbatim response, and the full SMTP transcript of the ingest conversation. Nine times out of ten the answer is on the mail’s detail page — this guide maps what you see there to a cause and a fix.

Find your symptom below (the literal error codes are in the headings, so Ctrl-F for the one you’re staring at).

Connecting and authenticating

AUTH is rejected with 538

Meaning: you tried to authenticate on a plaintext connection. Mailway never accepts credentials in the clear.

Fix: negotiate TLS before AUTH — use STARTTLS on a submission port (587, 25, 2525, 2587, 588) or connect with implicit TLS on 465 or 2465. Most libraries do this automatically once you set the right port and enable TLS. See the ports table.

The connection times out or is refused

Meaning: your platform is blocking outbound SMTP, not Mailway rejecting you — this is extremely common. GCP blocks port 25 permanently; DigitalOcean blocks 25, 465 and 587; AWS blocks 25 by default.

Fix: try another port — Mailway listens on seven for this exact reason (587 → 2525 → 2587 → 588, or 465 → 2465). Same host, same credentials. Whatever your network lets out, one gets through.

Auth fails intermittently with 454

Meaning: a temporary throttle, not a bad credential — Mailway’s auth backend was rate-limited for a moment.

Fix: retry with backoff. Your credential is fine; don’t rotate it. A persistent 454 on every attempt is worth a support request.

Check the credential shape first

A valid SMTP username is mw_user_ + the credential’s ID core; the password is mw_pass_ + 40 characters. Credentials are per-project — a credential only sends through its own project’s providers. Pasting a key (mw_live_…) where a password belongs, or mixing projects, shows up as an auth failure.

Mail that doesn’t reach the inbox

A mail is stuck in accepted and never reaches delivered

Meaning: usually not a problem. accepted means a provider took the handoff; delivered means the recipient’s server confirmed receipt, reported back through delivery events. Only providers that emit those events can ever show delivered — today that’s Amazon SES and Mailtrap. Everything else stops at accepted by design, and that is not a failure.

Fix: if you want real delivered/bounced signal, use a provider that reports it and wire up its delivery events (SES: configuration set → SNS; Mailtrap: webhook). See the Amazon SES guide. Otherwise, read accepted as “the provider has it.”

A mail shows failed (console: “Rejected”)

Meaning: Mailway never sent it, on purpose. Two common causes:

• A recipient is on the project’s suppression list — auto-added from an earlier permanent bounce or complaint, or added manually. The send is blocked before it goes out.
• A single-recipient send hit a hard bounce — a permanent rejection (bad mailbox, blocked sender) stops the retry chain rather than hammering a dead address.

Fix: open the send attempt to see the classified error. If it’s a suppression you disagree with, un-suppress the address. If it’s a hard bounce, the recipient address is the problem.

A mail is bounced or soft_bounced

Meaning: a provider delivery event came back negative. Hard (bounced) is permanent — the address is invalid or blocking you, and a single-recipient hard bounce auto-adds the address to suppressions. Soft (soft_bounced) is transient — a full mailbox, greylisting, a momentary defer — and the provider keeps retrying.

Fix: hard bounces mean fix or drop the address. Soft bounces usually resolve themselves; a persistent one is a receiver-side issue. Filter your list with state:bounced to review them in bulk.

Mail is authenticated but lands in spam

Meaning: authentication passing is necessary, not sufficient — alignment, reputation, and content still decide placement.

Fix: work the deliverability guide. The most common BYOK cause is DMARC not aligned to your domain; a Mail Tester score points at the rest.

Quotas and limits

Sends are blocked with 550 or 452

Meaning: you’ve hit a plan quota at SMTP time.

• 550 (permanent) — the monthly message quota or the monthly data-volume cap is spent for this billing period.
• 452 (transient) — the daily send cap. It resets at 00:00 UTC; retry after that.

Fix: check usage against your plan quotas. The permanent 550 needs a plan change or the month to roll over; the daily 452 just needs to wait for the reset. (On the Send API the equivalents are 402 and 429 — see Errors.)

A message is rejected with 552

Meaning: the message exceeds the 25 MB SMTP size limit — the same ceiling the Send API enforces, so both doors accept exactly the same messages.

Fix: shrink it — host large attachments and link them, or split the send. The Send API’s attachment caps are listed under Limits.

Recipients over 50, or Amazon SES returns 554 … exceeds 50

Meaning: SES caps a message at 50 recipients, counting every To/Cc/Bcc header address. Mailway handles this for you — above the cap it fans the send out BCC-style across sub-50 chunks automatically (details). A raw 554 reaching your app means it came from somewhere Mailway’s fan-out didn’t cover.

Fix: you shouldn’t normally see it on relayed SMTP mail. On the Send API, requests over 50 recipients are rejected up front with 422 — batch them instead.

Fidelity and webhooks

A delivered mail doesn’t match what I sent

Meaning: the message was re-encoded rather than relayed byte-for-byte. This only happens when SMTP mail is routed through a structured-only API provider (SendGrid, Postmark, Brevo, Mandrill, Mailtrap) and an admin has explicitly enabled re-encoding for that project–provider pair. It’s off by default; without it, relayed mail skips those providers.

Fix: check the mail’s fidelity — relayed (byte-for-byte), constructed (born on the API/console), or re-encoded. Filter with fidelity:re-encoded to find affected mail. If you need every message byte-perfect, route through a raw-capable provider (SES, Mailgun) or leave re-encoding disabled. Full behavior: SMTP mail through API providers.

A webhook isn’t arriving

Meaning: your endpoint isn’t accepting the delivery, or the endpoint was auto-disabled after repeated failures.

Fix, in order:

• Your endpoint must respond 2xx quickly. Non-2xx (or a redirect — Mailway does not follow them) counts as a failure.
• Mailway retries a failed delivery on a backoff ladder and auto-disables an endpoint after 24h of continuous failure. Re-enable it in the console once it’s healthy.
• Verify you’re checking the HMAC signature correctly — a signature mismatch is often a raw-body/parsing bug on your side. The verification snippet is on the Webhooks page.
• Delivery is at-least-once — dedupe on (type, data.mail.uid) so a retry can’t double-process. A “missing” event is sometimes one your handler 200’d and dropped.

Triage from the mails list

The search box on the mails list turns these symptoms into filters. The operators:

Operator	Example	Finds
state:	state:failed	Mail in a lifecycle state (aliases: held, sent, rejected, soft)
to: / from:	to:user@example.com	An exact address or a fragment
provider:	provider:amazon-ses-smtp	Mail routed through a provider
fidelity:	fidelity:re-encoded	relayed / constructed / re-encoded
dkim:	dkim:fail	Sender-DKIM verdict on the stored message (pass / fail / none / error / unsupported)
rescued:	rescued:yes	Mail a failover saved (a later provider succeeded)
after: / before:	after:2026-07-01	A date window (after:D before:D+1 = one day)
last:	last:24h	A rolling window (s/m/h/d/w)
size:	size>5mb	The only operator that takes comparators
subject: / category:	subject:invoice	Subject substring / exact send category

They combine: state:failed after:2026-07-01, state:soft_bounced provider:amazon-ses-smtp, rescued:yes last:7d.

The state ladder

A mail sits in the highest state it has reached. Highest-priority first:

State	Meaning
complained	Recipient marked it as spam (delivery event)
bounced	Permanent hard bounce (delivery event)
delivered	Recipient’s server confirmed receipt (delivery event)
soft_bounced	Transient defer; the provider is retrying
accepted	A provider took the handoff — no delivery event yet
failed	Rejected before sending (suppression, or single-recipient hard bounce) — shown as “Rejected”
paused	Held (project paused, over daily cap, or awaiting release)
pending	In the pipeline, not yet handed to a provider

Getting help

If you’re stuck, a support request moves fastest with:

• the mail ID (m.01k8w9…) — it threads the whole pipeline together,
• which send attempt failed and the provider response it shows, and
• the SMTP transcript from the mail detail page, if it’s an ingest issue.