When a provider is failing your sends
You got a provider.critical email or webhook, or the Deliverability page is showing a
red banner. This is what it means and what to do.
What triggered it
Section titled “What triggered it”Notavia watches a rolling 15-minute window of delivery attempts per provider. It alerts when a provider is dead-ending your mail — not when it bounces, and not when it is merely slow.
Specifically, it fires when a provider has failed enough of your recent messages to be Critical for two consecutive checks (checks run every 5 minutes, so ~10 minutes of sustained badness). “Failed” here means the provider refused the message and there was nowhere left to go — the message did not get out.
It deliberately does not fire when:
- a provider failed but the next provider in your chain delivered the message. Nothing was lost, so it is not a 3am event. The Deliverability page still shows it red, and the failover feed shows every hop.
- your bounce or complaint rate spikes. That is a reputation problem, not an outage, and bounce feedback arrives minutes-to-hours late — a 15-minute window cannot see it. Watch the bounce and complaint rates on the Deliverability page instead.
First: is your mail going out?
Section titled “First: is your mail going out?”Open Deliverability and look at the failing provider’s card.
| What you see | What it means |
| --- | --- |
| Another provider in your chain has sent climbing | Your chain is doing its job. Mail is going out through the fallback. You are not in an outage — you are on your last line of defence. Fix the primary before it stops being a drill. |
| Every provider is failing, or you only have one | Your mail is not going out. Messages are retrying and will start dying. Treat as an incident. |
The failover feed on the same page shows the last 50 hand-offs with the provider’s own error text. That error is usually the whole answer.
Then: fix the provider
Section titled “Then: fix the provider”The error text in the feed tells you which of these it is.
Authentication failures (401, 403, invalid api key, revoked) — someone rotated or
deleted the key. Re-enter it in Settings → Providers. This is the most common cause by a
distance.
Rate limits and quota (429, quota exceeded, daily limit) — you have outgrown the plan
you are on with that provider, or a burst tripped it. Raise the limit with them, or let a
fallback absorb the overflow.
Provider outage (5xx, timeouts) — check their status page. There is nothing to fix on your
side; this is what a fallback provider is for.
Sender or domain rejected (from address not verified, domain not found) — the provider
no longer trusts your sender identity. Re-verify the domain with that provider.
If you have no fallback, add one now
Section titled “If you have no fallback, add one now”An outage on your only provider is an outage on your product. Add a second provider in Settings → Providers and order it below the primary. Notavia tries them in order on every send and moves to the next within the same send when one refuses — no configuration, no code.
This is the single highest-value thing you can do in response to this alert, and it takes about two minutes.
What happens to the messages that failed
Section titled “What happens to the messages that failed”They are not lost immediately. A message whose whole chain refused it is retried with backoff,
and only marked Failed once its attempts are exhausted. Fix the provider inside that window
and the queue drains on its own.
Messages that did die are visible in Delivery logs filtered to Failed, with the provider’s
error on each one.
When the alert clears
Section titled “When the alert clears”Notavia sends provider.recovered — and clears the banner — only when the provider has
actually delivered mail again, sustained across two consecutive checks.
It will not clear just because things went quiet. A dead provider stops producing traffic, and treating that silence as recovery would tell you the problem was fixed in the middle of an outage. So: keep some traffic flowing through the provider you just fixed, or the alert will correctly stay up.
Two consequences worth knowing:
- If your primary is broken and your fallback is delivering everything, the primary has zero successes of its own — so its alert stays up until the primary itself sends again. That is correct, and it is usually the thing that surprises people first.
- Recent failures stay in the 15-minute window. If you fixed the provider one minute ago, the window still holds the failures from before the fix, so the failure rate is still high. Give it ~15 minutes for those to age out, plus two checks. Sending a large burst of successful mail will also do it, but you need roughly nine successes for every failure still in the window — waiting is easier.
Turning it off
Section titled “Turning it off”Alerting is on by default for Live environments and off for Test (you break things in Test
on purpose). Toggle either on the Deliverability page. You need the CanManageConfig role — a
Viewer cannot silently switch off your production alerting.
Wiring it to a pager
Section titled “Wiring it to a pager”provider.critical and provider.recovered are webhook events. Subscribe an endpoint to them in
Settings → Webhooks and route them to PagerDuty, Opsgenie, or Slack. Dedupe on the event id:
it is stable for the life of one outage, so a retried delivery will not page you twice, and a new
outage on the same provider gets a new id.
See the webhooks guide
for the payload, and the ASP.NET Core SDK’s OnProviderCritical callback if you are on .NET.