Docs / Marketing and 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 and 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 | On: more than 2.5% hard bounces or 0.08% complaints | campaign settings |
| Workspace guard | On: more than 5% hard bounces or 0.3% complaints over 7 days | workspace settings |
| Warm-up of new sending domains | On: 50 emails on the first day, 50,000 per day after 21 days | warmup settings, per domain |
| 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 | On | engagementOrdering |
| Address quality | On: typos, domains without a mail server and temporary addresses are skipped | quality.exclude, per campaign |
| Sunsetting | Off | sunset settings |
| Best time to send | Chosen per campaign | Schedule step |
| Provider suppression lists | On: imported when connected and every 6 hours; sharing ours with providers off | providerSync settings |
| Delivery status checks | Automatic: for providers whose webhooks did not arrive in 24 hours | statusPolling settings |
| Repeated soft bounces | On: 3 soft bounces in 7 days pause the address for 14 days | softBounces settings |
| Recipient and campaign affinity | On | routing settings |
| 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 | On: more than 4% hard bounces or 0.1% complaints over 24 hours or 7 days | providerHealth settings |
| 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 |
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.
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
pausedReasonsays 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.pausedwebhook event is sent (see 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.
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}/schedulereturns 409campaigns_blockedwith the reason.- A scheduled campaign whose time arrives is paused with
pausedReason.codeworkspace_guard. - Re-engagement emails (sunsetting) are not sent.
- Transactional email is not affected.
- A
campaigns.blockedwebhook 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.
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:
warmingstarts the warm-up today ("restart": truerestarts a running one),establishedmarks a domain that already has a sending reputation elsewhere,offturns warm-up off for that domain.
Turn warm-up off for every domain with {"warmup":{"enabled":false}}.
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.
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.
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 (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_mxfilters contacts (uncheckedmatches contacts not checked yet).- A campaign includes contacts with address problems when
delivery.includeQualityIssuesistrue. Which problems are skipped by default isquality.exclude. POST /v1/deliverability/quality/checkchecks up to 1,000 addresses without storing them ("dns": falseskips the lookup).POST /v1/deliverability/quality/recheckchecks every contact of the workspace again.
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.includeInactiveistrue. - An open or click at any time (including on transactional email) restores them to
subscribed. POST /v1/deliverability/inactive/restorewithidsor"all": truerestores them; the dashboard has a Restore all button.
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.
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.
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).
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.
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.
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.
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.
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.
Recipient and campaign affinity
- Recipient affinity (
routing.recipientAffinity): the router prefers the provider that last accepted email for the recipient. Inautomode 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.
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.
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.
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.