---
title: "Deliverability safeguards"
description: "Everyone who bounces or complains anywhere is blocked everywhere. OneSend keeps one suppression list for the whole workspace and checks it before choosing a provider, whichever provider would send."
url: https://onesend.email/docs/deliverability/
---
# Deliverability safeguards

**Everyone who bounces or complains anywhere is blocked everywhere.** OneSend keeps one suppression list for the whole workspace and checks it before choosing a provider, whichever provider would send. It is filled from every place a provider tells us about a bad address: provider webhooks, delivery status checks through the provider API, each provider's own suppression list (imported when you connect it and every 6 hours), and rejections when sending. See [One suppression list for every provider](#one-suppression-list) and [Reputation-safe routing](#reputation-safe-routing).

OneSend sends through provider accounts you own, often on free plans. Providers suspend accounts whose bounce or complaint rates get too high, and mailbox providers (Gmail, Outlook, Yahoo) distrust sudden volume from a domain they have not seen. The safeguards on this page keep campaigns within those limits. They apply to campaigns; transactional email is never paused or held.

In the dashboard, open **Deliverability** (under **Sending**). The API is under `/v1/deliverability`; the full schemas are in the API reference at `/docs` (tag **Deliverability**).

| Safeguard | Default | Where to change it |
|---|---|---|
| [Automatic campaign pause](#automatic-campaign-pause) | On: more than 2.5% hard bounces or 0.08% complaints | `campaign` settings |
| [Workspace guard](#workspace-guard) | On: more than 5% hard bounces or 0.3% complaints over 7 days | `workspace` settings |
| [Warm-up of new sending domains](#warm-up) | On: 50 emails on the first day, 50,000 per day after 21 days | `warmup` settings, per domain |
| [Pacing per mailbox provider](#pacing-per-mailbox-provider) | On: 1,000 per provider on the first day, then at most 2× the best previous day | `pacing` settings |
| [Engaged contacts first](#engaged-contacts-first) | On | `engagementOrdering` |
| [Address quality](#address-quality) | On: typos, domains without a mail server and temporary addresses are skipped | `quality.exclude`, per campaign |
| [Sunsetting](#sunsetting) | Off | `sunset` settings |
| [Best time to send](#best-time-to-send) | Chosen per campaign | Schedule step |
| [Provider suppression lists](#provider-suppression-lists) | On: imported when connected and every 6 hours; sharing ours with providers off | `providerSync` settings |
| [Delivery status checks](#delivery-status-checks) | Automatic: for providers whose webhooks did not arrive in 24 hours | `statusPolling` settings |
| [Repeated soft bounces](#repeated-soft-bounces) | On: 3 soft bounces in 7 days pause the address for 14 days | `softBounces` settings |
| [Recipient and campaign affinity](#affinity) | On | `routing` settings |
| [Spillover cap](#spillover-cap) | On: at most 10% of a campaign (at least 20 emails) per hour moves to other providers | `routing.spilloverShare`, `routing.spilloverMinPerHour` |
| [Provider health](#provider-health) | On: more than 4% hard bounces or 0.1% complaints over 24 hours or 7 days | `providerHealth` settings |
| [Stream separation](#stream-separation) | Off (every provider sends both) | `stream` per routing policy step |

## Settings

`GET /v1/deliverability/settings` returns every setting with its current value. `PATCH /v1/deliverability/settings` changes only the fields you send. Values outside these ranges are refused with 400 `invalid_settings`:

| Setting | Range |
|---|---|
| `campaign.bounceRate` | 0.005 to 0.1 (0.5% to 10%) |
| `campaign.complaintRate` | 0.0002 to 0.005 |
| `campaign.minSample` | 50 to 10,000 emails |
| `campaign.minSampleFraction` | 0.01 to 0.5 |
| `workspace.bounceRate` | 0.01 to 0.2 |
| `workspace.complaintRate` | 0.0005 to 0.02 |
| `workspace.windowDays` | 1 to 30 |
| `warmup.startPerDay` | 10 to 2,000 |
| `warmup.targetPerDay` | 500 to 1,000,000 (larger than `startPerDay`) |
| `warmup.days` | 5 to 60 |
| `pacing.firstDayPerProvider` | 50 to 100,000 |
| `pacing.growth` | 1.2 to 5 |
| `sunset.campaigns` | 3 to 50 |
| `sunset.days` | 30 to 730 |
| `sunset.graceDays` | 3 to 60 |
| `routing.recipientAffinity` | `auto`, `recipient` or `off` |
| `routing.spilloverShare` | 0.01 to 1 (1 = no cap) |
| `routing.spilloverMinPerHour` | 1 to 100,000 |
| `providerHealth.bounceRate` | 0.005 to 0.25 |
| `providerHealth.complaintRate` | 0.0001 to 0.02 |
| `providerHealth.minSample24h` / `minSample7d` | 20 to 100,000 / 20 to 1,000,000 emails |
| `providerHealth.severeFactor` | 1.2 to 10 |
| `providerHealth.cooldownHours` | 1 to 168 |
| `softBounces.count` / `windowDays` / `suppressDays` | 2 to 20 / 1 to 30 / 1 to 90 |
| `providerSync.intervalHours` | 1 to 168 |
| `statusPolling.mode` | `auto`, `always` or `off` |
| `statusPolling.quietHours` / `maxAgeHours` | 1 to 720 / 6 to 168 |

```bash
curl -X PATCH "$ONESEND_BASE_URL/v1/deliverability/settings" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"campaign":{"bounceRate":0.02},"warmup":{"startPerDay":100,"days":14}}'
```

`GET /v1/deliverability` returns the page data: bounce, complaint and open rates for the last 7 and 30 days, the settings, the workspace guard, warm-up per sending domain, paused campaigns with their reasons, contact counts by address quality, inactive contacts and the best time to send.

<a id="automatic-campaign-pause"></a>
## Automatic campaign pause

While a campaign sends, OneSend checks its rates after each bounce and complaint:

- **Hard bounce rate** = hard bounces / emails sent.
- **Complaint rate** = spam complaints / emails delivered.

The rates are judged once enough emails were sent: `minSample` (200), or `minSampleFraction` of the recipients (5%) when that is smaller, but never fewer than 20 emails. Above `bounceRate` or `complaintRate`, the campaign is paused:

- Emails not yet handed to a provider are held, as with a manual pause.
- The campaign's `pausedReason` says why, for example `{ "code": "bounce_rate", "auto": true, "value": 0.0476, "threshold": 0.025, "sample": 210, "message": "Paused automatically: 4.76% of the 210 emails sent so far hard-bounced (limit 2.5%). …" }`.
- A `campaign.paused` webhook event is sent (see [Webhooks](https://onesend.email/docs/webhooks/)), and the dashboard shows a banner and lists the campaign on the Deliverability page.

The campaign stays paused until someone resumes it (`POST /v1/campaigns/{id}/resume`). After a resume, the rates are judged again on the emails sent from then on, with a new minimum sample, so the campaign pauses again if the problem continues.

Manual pauses have `pausedReason.code` `manual` and `auto: false`.

<a id="workspace-guard"></a>
## Workspace guard

When all email of the workspace over the last 7 days (`windowDays`) has more than `workspace.bounceRate` hard bounces or `workspace.complaintRate` complaints, with at least `workspace.minSample` emails sent, new campaign sends are held:

- `POST /v1/campaigns/{id}/schedule` returns 409 `campaigns_blocked` with the reason.
- A scheduled campaign whose time arrives is paused with `pausedReason.code` `workspace_guard`.
- Re-engagement emails (sunsetting) are not sent.
- Transactional email is not affected.
- A `campaigns.blocked` webhook event is sent once.

`GET /v1/deliverability/guard` returns the state. The block stays until the workspace owner or an admin acknowledges it with `POST /v1/deliverability/acknowledge` (a signed-in session; API keys cannot). After that, the guard judges only email sent after the acknowledgement.

<a id="warm-up"></a>
## Warm-up

A sending domain (the domain of a campaign's sender address, such as `news.acme.dev`) that has not sent campaign email before is warmed up when its first campaign starts. Its daily campaign volume grows from `startPerDay` to `targetPerDay` over `days` days (a geometric ramp: 50, 71, 100, 141, … with the defaults). Every campaign from the domain shares the day's cap. After the last day the domain is warmed up and no longer limited.

The campaign plan shows the effect, for example `{ "perDay": 60, "days": 2, "limitedBy": "warmup", "domain": "fresh.dev", "reason": "Sends over 2 days because fresh.dev is warming up (day 1 of 21: up to 50 campaign emails on the first day, …)." }`. Emails for later days are scheduled a few minutes after the providers' daily reset, as with quota-based plans.

`GET /v1/deliverability/warmup` lists sending domains with their status (`new`, `warming`, `complete`, `off` or `established`), the day of the warm-up, today's limit and the emails planned today. `PATCH /v1/deliverability/warmup/{domain}` with `status`:

- `warming` starts the warm-up today (`"restart": true` restarts a running one),
- `established` marks a domain that already has a sending reputation elsewhere,
- `off` turns warm-up off for that domain.

Turn warm-up off for every domain with `{"warmup":{"enabled":false}}`.

<a id="pacing-per-mailbox-provider"></a>
## Pacing per mailbox provider

Recipients are grouped by mailbox provider: Gmail (`gmail.com`, `googlemail.com`, and domains whose MX points to Google), Outlook (`outlook.com`, `hotmail.*`, `live.*`, `msn.com`, and domains hosted at Microsoft), Yahoo (`yahoo.*`, `aol.com`, `ymail.com` and others) and everyone else. For each sending domain, the first day to Gmail, Outlook and Yahoo is capped at `firstDayPerProvider`, and each later day at `growth` × the best previous day to that provider (over the last 30 days). Other providers are not paced.

Pacing, warm-up and your providers' quotas combine: each recipient goes out on the first day that has room under all three. The plan's `limitedBy` says which one spread the campaign (`quota`, `warmup` or `pacing`).

Warm-up and pacing do not apply when only the Sandbox provider sends campaigns (it delivers nothing). To preview them with Sandbox, set `includeSandbox: true`.

<a id="engaged-contacts-first"></a>
## Engaged contacts first

When a campaign starts, each recipient gets a rank: opened or clicked in the last 30 days, 90 days, 180 days, or older or never. Recipients are sent in that order, so the first emails go to people who are likely to open them, and the recipients pushed to later days by warm-up or pacing are the least engaged ones.

<a id="address-quality"></a>
## Address quality

Every contact gets a `quality` value when it is created or its address changes, and a background check adds the mail server lookup:

| `quality` | Meaning | Campaigns |
|---|---|---|
| `ok` | No problem found | Included |
| `typo` | The domain looks like a typo of a common one (`gmial.com`); `qualitySuggestion` holds the corrected address | Skipped by default |
| `no_mx` | The domain has no MX or A record, so it cannot receive email | Skipped by default |
| `disposable` | A temporary-address domain | Skipped by default |
| `role` | A team or system address such as `info@` or `support@` | Included (flagged only) |
| `invalid` | Not a valid address | Skipped by default |
| `null` | Not checked yet | Included |

Mail server lookups use the same DNS-over-HTTPS resolver as the [deliverability tools](https://onesend.email/docs/tools/) (`ONESEND_DNS_OVERRIDES` applies in development) and are cached per domain for 7 days. When DNS cannot be reached, the address is not flagged. Widely used mailbox domains are never looked up.

- `GET /v1/contacts?quality=typo,no_mx` filters contacts (`unchecked` matches contacts not checked yet).
- A campaign includes contacts with address problems when `delivery.includeQualityIssues` is `true`. Which problems are skipped by default is `quality.exclude`.
- `POST /v1/deliverability/quality/check` checks up to 1,000 addresses without storing them (`"dns": false` skips the lookup).
- `POST /v1/deliverability/quality/recheck` checks every contact of the workspace again.

<a id="sunsetting"></a>
## Sunsetting

Off by default. When on, a subscribed contact who has not opened or clicked in the last `campaigns` campaigns (rule `campaigns`) or `days` days (rule `days`) gets one re-engagement email: the template `templateId`, from `fromEmail` and `fromName`, sent as campaign email with an unsubscribe link and the tag `reengagement`. If they do not open or click within `graceDays`, their status becomes `inactive`:

- Inactive contacts are not unsubscribed and not deleted. Campaigns skip them unless `delivery.includeInactive` is `true`.
- An open or click at any time (including on transactional email) restores them to `subscribed`.
- `POST /v1/deliverability/inactive/restore` with `ids` or `"all": true` restores them; the dashboard has a **Restore all** button.

```bash
curl -X PATCH "$ONESEND_BASE_URL/v1/deliverability/settings" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"sunset":{"enabled":true,"rule":"campaigns","campaigns":10,"graceDays":14,"templateId":"tpl_…","fromEmail":"news@acme.dev","fromName":"Acme"}}'
```

Sunsetting runs every 10 minutes; `POST /v1/deliverability/sunset/run` runs it now.

<a id="best-time-to-send"></a>
## Best time to send

`GET /v1/deliverability/best-time` returns first opens per UTC hour over the last 30 days (from the statistics rollup), the hour with the most opens in UTC and in the workspace time zone, and a sentence for the schedule step. A suggestion needs at least 20 opens.

Schedule a campaign with `"bestTime": true` (`POST /v1/campaigns/{id}/schedule`, saved as `delivery.bestTime`) to send each email at the hour its recipient usually opens, within 24 hours of the start. A contact's own hour is used once they have opened 3 emails; otherwise the workspace's best hour; without either, the email goes out at the start. On days after the first (warm-up, pacing or quota), the same hour is used on that day.

## Campaign review

`GET /v1/campaigns/{id}/safeguards` lists what applies to a campaign: the pause thresholds, warm-up and pacing of its sending domain, the combined plan, how many contacts are skipped for address problems or inactivity, the workspace guard and the best time. The dashboard shows it in the campaign editor's review step.

<a id="reputation-safe-routing"></a>
## Reputation-safe routing

### Domain reputation and IP reputation, in plain words

Mailbox providers such as Gmail and Outlook judge two things when your email arrives:

- **Your domain.** Every provider signs your email with DKIM for your own domain (the DNS records you add once). Gmail and others remember how people react to email signed by that domain, whichever provider sent it. This domain reputation follows you across providers: bounces and spam complaints through SES hurt the same domain that Brevo signs for.
- **The sending servers (IP addresses).** Each provider sends from its own servers. Their reputation belongs to the provider and its other customers. When you pool quota across providers, your email moves between these server reputations.

So OneSend does two things: it makes sure a bad address found anywhere is never mailed again through any provider (protecting your domain), and it keeps traffic steady per provider (so a provider's servers see consistent, expected volume from you).

<a id="one-suppression-list"></a>
### One suppression list for every provider

Each entry records where it came from (`origin`): `webhook`, `webhook_unmatched`, `poll` (a delivery status check), `sync` (the provider's own list), `send` (refused when sending), `manual`, `import`, `escalation` (repeated soft bounces), `unsubscribe` or `api`, with the provider and connection, the provider's reason text and, for temporary entries, when it ends (`expiresAt`). Rules when sources disagree: a permanent entry replaces a temporary one, the stronger reason wins (complaint over hard bounce over unsubscribe), the wider scope wins, and nothing ever weakens an entry. Contacts erased under GDPR are never re-imported from a provider list.

A provider webhook counts as `webhook` (the provider's word) only when it names a message we sent to that address through the same connection the webhook arrived on within the last 30 days (for a message that records no connection: a delivery attempt of it through that same connection in that time; another connection of the same provider does not count). Any other bounce or complaint by webhook is `webhook_unmatched`: anyone who has the webhook URL could have sent it. It still stops campaign and API mail to the address, but never system email (security alerts, sign-in and invitation links), which only provider-vouched hard bounces and complaints (`webhook`, `poll`, `sync`, `send`) stop. A `webhook_unmatched` event never replaces the origin of a vouched entry: the vouched origin is kept (a hard bounce can become a complaint), and an entry that did not stop system email (an unsubscribe, say) does not start to. Entries written before `origin` was recorded (before migration 0025, `origin` empty) count as vouched when their `source` has the shape of a provider event (`<provider>:msg_…` or `sync:…`), the same rule that decides whether they stop system email, so an unmatched event cannot weaken them either. A vouched event for the same reason replaces a `webhook_unmatched` entry.

<a id="provider-suppression-lists"></a>
### Provider suppression lists

Each provider keeps its own list, so an address that hard-bounced at SES is still "fresh" at Brevo. OneSend imports each provider's list when you connect it, then every `providerSync.intervalHours` (6), and on **Sync now** (Suppressions page, provider page, `POST /v1/suppressions/sync`). Passes are incremental where the provider can filter by date (changes since the last completed pass, with an hour of overlap), keep a cursor per connection, respect the provider's rate limit, read bounded pages and stop within the job's query budget (Cloudflare D1), continuing in the next job. Which providers support it: [Provider catalog](https://onesend.email/docs/providers/#suppression-sync-and-status-checks).

`providerSync.push` (off by default) also adds our own permanent suppressions (hard bounces, complaints, unsubscribes; not the ones that came from that provider) to providers that support it: Amazon SES (bounces and complaints only), Postmark (the connection's message stream), Mailgun (the default sending domain, or up to 10 domains) and SparkPost. It is off by default because a provider account may be shared with other apps, whose email would then be suppressed too.

<a id="delivery-status-checks"></a>
### Delivery status checks (polling)

When webhooks cannot reach your server (the Mac app on its own, no public URL, webhooks never set up), OneSend asks the provider API for the status of recent emails that have no final event: 5 minutes, 30 minutes, 2 hours and 12 hours after sending, then every 12 hours until 72 hours. Delivered emails are checked again from 12 hours (a spam complaint can follow a delivery). Results go through the same path as webhooks, so a bounce or complaint found this way suppresses the address for every provider. `statusPolling.mode`: `auto` (default; connections without a webhook in `quietHours`, 24), `always` or `off`. The provider page shows when a webhook last arrived; after 7 days without one it says to connect webhooks or rely on status checks.

<a id="repeated-soft-bounces"></a>
### Repeated soft bounces

A soft bounce is a temporary failure (mailbox full, server busy). After `softBounces.count` (3) soft bounces within `windowDays` (7), the address is paused for every provider for `suppressDays` (14), reason `soft_bounce_repeated`. The entry ends on its own; a later hard bounce or complaint makes it permanent.

<a id="affinity"></a>
### Recipient and campaign affinity

- **Recipient affinity** (`routing.recipientAffinity`): the router prefers the provider that last accepted email for the recipient. In `auto` mode Gmail, Microsoft and Yahoo addresses are grouped per mailbox provider (all your Gmail traffic stays on one provider while it can); other addresses are tracked per address. Only a keyed hash of the address is stored (`recipient_affinity`).
- **Campaign affinity** (`routing.campaignAffinity`): a campaign gets a home provider (the first eligible one in policy order) and sends through it while it can. If the home provider is paused by you or removed from the policy, the campaign moves home.

Both are soft preferences: they only reorder providers that are already eligible (active, healthy, within quota, allowed by the policy and its rules). Failover order and priorities are unchanged; a forced connection ignores them.

<a id="spillover-cap"></a>
### Spillover cap

When a campaign's home provider is full or unavailable, at most `routing.spilloverShare` (10%) of the campaign, and at least `spilloverMinPerHour` (20), may move to other providers per hour. The rest waits until the next hour (`deferred` event with `reason: "spillover_cap"`) instead of flooding a provider that has not sent this campaign before. Transactional email is never capped. `spilloverShare: 1` turns the cap off.

<a id="provider-health"></a>
### Provider health

Hard bounce and complaint rates per connection over 24 hours and 7 days, each with a minimum sample (`minSample24h` 250, `minSample7d` 1,000) and at least 3 bounces or complaints. Above `providerHealth.bounceRate` (4%) or `complaintRate` (0.1%) the provider is taken out of rotation for campaigns; above `severeFactor` (2.5) times a threshold also for transactional email (`transactional`), where it is still used when no other provider can send. After `cooldownHours` (24) it is judged again on email sent since it was taken out, and put back when those rates are below the thresholds. Each change records a `connection.health` event, shows in the dashboard alerts and on the provider page; **Put back in rotation** (`POST /v1/connections/{id}/health/reset`) ends it at once.

<a id="stream-separation"></a>
### Stream separation

Each routing policy step can be limited to transactional or campaign email (`stream: "transactional"` or `"broadcast"`). The routing page warns when no enabled provider is left for one kind.

## Webhook events

| Event | When | `data` |
|---|---|---|
| `campaign.paused` | A safeguard paused a campaign | `campaignId`, `campaignName`, `code` (`bounce_rate` or `complaint_rate`), `reason`, `value`, `threshold`, `sample`, `auto` |
| `campaigns.blocked` | The workspace guard started holding new campaigns | `code`, `reason`, `bounceRate`, `complaintRate`, `sample` |
| `connection.health` | A provider was taken out of rotation, escalated, eased or put back | `status` (`ok`, `marketing_paused`, `paused`), `previous`, `change`, `code`, `value`, `threshold`, `window`, `sample`, `reason`, `connectionName` |

## Limits for constrained runtimes

On runtimes with a cap on database queries per invocation (Cloudflare D1 allows 1,000), the campaign jobs can stop early and continue in a new job. Set `deps.limits.campaigns` (`CampaignLimits` in `apps/server/src/deps.ts`): `batchSize` (recipients per `campaign_batch`, default 200), `startPageSize` (contacts per materialization page, default 2,000), `queryBudget` with `queryCount` (a counter of queries run so far), and `timeBudgetMs`. The warm-up, pacing and best-time lookups run inside the same budget. The provider suppression sync (`provider_sync`), status checks (`status_poll`) and provider health (`provider_health`) jobs use the same query budget and a 20-second time budget, and continue in a new job.
