> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Email deliverability
> Improve inbox placement by managing sender reputation, reducing bounces and spam complaints, and following email hygiene best practices.
Use this guide to understand why emails reach the inbox, land in spam, or get blocked, and which OneSignal tools to check when deliverability slips. Deliverability depends on your sender reputation, email content, [domain alignment](./email-dns-configuration) (DKIM and SPF matching your From: domain), and recipient engagement. Inbox providers (Gmail, Outlook, Yahoo, Apple) assess every incoming email to filter out unwanted or harmful messages.
## Volume thresholds: warm-up vs bulk sender
These limits are related but different:
| Threshold | What it means | What to do |
| - | - | - |
| About **2,000+ emails per day** from a new or cold domain | High volume without a sending history triggers spam filters | [Warm up](./email-warm-up) gradually with Auto Warm Up |
| **5,000+ emails per day to Gmail or Yahoo** | Gmail and Yahoo permanently classify your domain as a [bulk sender](#gmail-and-yahoo-bulk-sender-requirements) | Meet DMARC, one-click unsubscribe, and spam-rate requirements before you cross this line |
Warm up before you hit bulk-sender volume. Crossing 5,000/day to Gmail or Yahoo without a healthy reputation is hard to recover from.
## Reputation
Your **email sending reputation**, assigned by inbox providers, is a key driver of deliverability. It determines how much they accept from you, whether messages get blocked, and where they land (inbox, promotions, or spam). See [Inbox placement](#inbox-placement).
Reputation works like a credit score: it rises or falls based on the performance of your past emails.
### What helps reputation
* Proper [email authentication](./email-dns-configuration) (SPF, DKIM, DMARC)
* High engagement (e.g., [opens](#opened), [clicks](#clicked), replies)
* Clean, verified lists
* Consistent email sending patterns
### What hurts reputation
* High [spam complaint](#spam-complained) rates. See [Monitor spam reports](./email-reputation-best-practices#monitor-spam-reports-and-complaints).
* High [bounce](#bounced) rates. See [Avoid invalid emails](./email-reputation-best-practices#avoid-invalid-emails).
* Sending to [spam traps](#spam-traps). See [Set up a clear opt-in process](./email-reputation-best-practices#set-up-a-clear-opt-in-process).
### Which spam and bounce limits apply
Use the right threshold for the right system:
| Limit | Source | What it means |
| - | - | - |
| Bounce rate below **5%**; spam complaint rate below **0.08%** | OneSignal [Acceptable Use Policy](https://onesignal.com/aup) | Exceeding these can lead to blocking and AUP enforcement |
| Spam rate below **0.10%**; never reach **0.30%** or higher | [Google's Email Sender Guidelines](https://support.google.com/a/answer/81126?hl=en#spam-rate) | Gmail Postmaster Tools spam rate for your domain |
| Spam complaint rate below **0.3%** | Gmail and Yahoo [bulk sender](#gmail-and-yahoo-bulk-sender-requirements) rules | Required for high-volume senders; aim for Google's 0.10% target |
The OneSignal **Reported spam rate** (Reputation dashboard) excludes Gmail and Apple. For Gmail's rate, [connect Google Postmaster Tools](./google-postmaster-tools). See [How spam rate is calculated](#how-spam-rate-is-calculated).
### Where to monitor reputation
If you use OneSignal Email:
* **Settings > Email > Reputation** for overall bounce and reported spam rates
* **Messages > Email > [Deliverability insights](./email-deliverability-insights)** for the same metrics broken down by inbox provider
If you send through a third-party provider (e.g., SendGrid, Mailchimp, Mailgun), use that provider's dashboard for complaints and bounces.
### How reputation metrics are calculated
* **Bounce rate** = permanent bounces ÷ total sent
* **Reported spam rate** = spam complaints from feedback-loop providers ÷ delivered emails to those providers. Apple and Gmail do not report per-recipient complaints, so their deliveries are excluded from this rate.
See [How spam rate is calculated](#how-spam-rate-is-calculated) for Gmail and Apple details.
Actionable steps to build and maintain a healthy sending reputation: opt-in, monitoring, frequency, warm-up, and list hygiene.
## Gmail and Yahoo bulk sender requirements
Gmail and Yahoo classify any domain sending **5,000 or more messages per day specifically to Gmail or Yahoo addresses** as a **bulk sender**. The classification is permanent and applies even if your daily volume later drops below 5,000.
Bulk senders must meet stricter requirements or face throttling and spam folder placement.
| Requirement | Applies to |
| - | - |
| SPF authentication | All senders |
| DKIM authentication | All senders |
| DMARC published and aligned with SPF or DKIM | Bulk senders |
| One-click unsubscribe in marketing email | Bulk senders |
| Spam complaint rate below **0.3%** (Google recommends staying below **0.10%**) | All senders |
| Valid forward and reverse DNS records (PTR / FCrDNS) | All senders |
| TLS-encrypted transmission | All senders |
| RFC 5322 message formatting | All senders |
OneSignal handles forward/reverse DNS, TLS, and message formatting for you. You're responsible for [SPF, DKIM, and DMARC](./email-dns-configuration), keeping your complaint rate low, and including a working unsubscribe link. Monitor Gmail's spam rate with [Google Postmaster Tools](./google-postmaster-tools) (it does not appear in the overall Reputation dashboard).
OneSignal-specific setup steps to meet the Gmail and Yahoo bulk sender requirements.
## Key deliverability concepts
These terms appear in your email reports and reputation dashboard.
### Unsubscribed
Recipients who opt out via the unsubscribe link in your emails. These recipients are suppressed automatically to ensure compliance and protect your reputation. Honor unsubscribe requests promptly. It is required by regulations like CAN-SPAM and protects your sender reputation.
Manage unsubscribe links, List-Unsubscribe headers, suppression rules, and resubscription workflows.
Replace the default unsubscribe link with a branded, multi-language preferences page.
### Bounced
Emails that fail to deliver because the address is permanently invalid (it does not exist or is misspelled). Bounce data is stored in your [suppression list](#suppression-list) and is also visible in [Event Streams](./event-streams).
### Failed
Emails that could not be delivered after retry attempts. Failed sends are **not** added to your suppression list, and the email may be retried on future sends. Failures appear in [Email Message Reports > Audience Activity](./email-message-reports#audience-activity) and [Event Streams](./event-streams).
Common reasons:
| Failure | Typical cause |
| - | - |
| **Too old** | Recipient server deferred the message for the full 8-hour retry window (often a security gateway). See [Too old failures](./email-troubleshooting#too-old-failures). |
| **Mailbox full** | Recipient mailbox is over quota. No sender-side fix. |
| **DNS or domain issues** | Invalid recipient domain or missing MX records (often list typos like `gmial.com`). |
| **Inbox provider policy block** | Content, reputation, or authentication rejection by the provider. |
| **Authentication failure** | SPF, DKIM, or DMARC failed. See [Email DNS configuration](./email-dns-configuration). |
### Spam complained
When recipients mark your email as spam, it triggers a spam complaint (also called a spam report).
Common reasons: irrelevant content, excessive frequency, or recipients who did not opt in. Follow the [email reputation best practices](./email-reputation-best-practices) to keep complaints low. Spam complaint events are available in [Event Streams](./event-streams).
#### How spam rate is calculated
A **feedback loop** is how some inbox providers notify senders when a recipient marks mail as spam. Yahoo and Outlook provide feedback loops. Gmail and Apple do not.
The OneSignal **Reported spam rate** is:
**spam complaints from feedback-loop providers ÷ emails delivered to those providers**
Apple and Gmail deliveries are excluded from both the numerator and the denominator. Their complaints never appear in this rate. That is an industry-wide limitation, not a OneSignal limitation. Sustained rates above **0.3%** can hurt placement at major providers. Aim for Google's **0.10%** target when monitoring Gmail in Postmaster Tools. OneSignal's AUP expects complaint rates below **0.08%** on the reported (feedback-loop) rate. See [Which spam and bounce limits apply](#which-spam-and-bounce-limits-apply).
To see **Gmail's** spam rate, [connect Google Postmaster Tools to OneSignal](./google-postmaster-tools): verify your sending domain with Google and add `mailmonitor@onesignal.com` as a managed user. The Gmail figure then appears in [Deliverability insights](./email-deliverability-insights) (**Messages > Email**) next to other providers. Full Gmail charts and domain reputation (High / Medium / Low / Bad) remain in Postmaster Tools.
Connect Postmaster Tools to OneSignal for Gmail spam rate and domain reputation.
View Gmail spam rate next to Outlook, Yahoo, Apple, and other providers.
### Suppression list
Your app's internal list of email addresses OneSignal will not send to, typically after a hard bounce or spam complaint. Manage entries on the [Suppressions](./suppressions) page. This is not the same as an external [blocklist](#blocklists).
### Blocklists
External or inbox-provider-managed lists of spammy or harmful IPs and domains (for example [Spamhaus](https://www.spamhaus.org/)). Being listed causes deliverability problems across many inboxes. Check your domain or IP status with those providers.
### Spam traps
Spam traps are addresses not used by real people. Inbox providers and anti-spam organizations plant them to catch poor list hygiene. Sending to them can put your domain or IPs on a [blocklist](#blocklists).
| Type | What it is |
| - | - |
| **Pristine** | Addresses created only to act as traps (often on public sites or purchased lists) |
| **Recycled** | Former real inboxes repurposed as traps after abandonment |
| **Typo** | Domains with common misspellings (`gnail.com`, `tahoo.com`, `gmail.con`) |
List-cleaning tools often miss traps. Prevent them with confirmed (double) opt-in, and remove unengaged recipients so traps never stay on your active list. See [Set up a clear opt-in process](./email-reputation-best-practices#set-up-a-clear-opt-in-process), [Magic Link double opt-in](./example-verification-magic-link-otp#setting-up-double-opt-in-with-onesignal), and [Wait Until](./journeys-actions#wait-until) journeys to sunset non-engagers.
## Email address validation
Validate addresses before they reach your audience. Validation flags typos, invalid domains, role-based addresses, and disposable email services that raise bounce rates and hurt reputation.
Validate email addresses during CSV import and in bulk to reduce bounces and protect your sender reputation.
## Engagement metrics
### Opened
The number of times recipients open your email messages. Open rates reflect subject lines, targeting, and your From name and address. View opens in [Email Message Reports](./email-message-reports).
Open rates are over-reported for Apple Mail recipients because Mail Privacy Protection prefetches images. Compare opens with clicks and [CTOR](./email-message-reports#open-rate) for a more reliable engagement signal.
### Clicked
The number of times recipients click links in your emails. Clicks require an open, so they are a stronger engagement signal than opens alone. View clicks in [Email Message Reports](./email-message-reports).
## Inbox placement
Inbox placement is where your emails land inside the recipient's mailbox. Placement affects whether mail is seen and engaged with.
### Primary
The Primary tab is typically where important and personal mail lands. Primary placement usually signals good reputation and relevance.
### Promotions
The Promotions tab holds promotional or marketing mail. Providers categorize messages using reputation and content signals.
Landing in Promotions is not a sign of bad reputation. Marketing mail often performs better there because recipients expect deals when they open that tab. Gmail also surfaces Promotions intentionally.
To reach Primary more often, reduce heavy promotional language, personalize content, and ask recipients to move your mail to Primary.
### Spam
Emails filtered into spam or junk. Causes include suspicious content, filter triggers, or low sender reputation.
Spam placement usually means reputation trouble. Check bounce and complaint rates against the [limits above](#which-spam-and-bounce-limits-apply). Google expects Postmaster spam rates below **0.10%** and treats **0.30%** as critical. Follow [email reputation best practices](./email-reputation-best-practices). If placement does not look reputation-related, verify DMARC alignment with a tool like [About My Email](https://aboutmy.email/).
## FAQ
### What is the difference between reputation and deliverability?
Reputation is the score inbox providers assign to your sending domain based on past email performance. Deliverability is the outcome: whether your emails reach the inbox, land in spam, or get blocked. A good reputation is the primary driver of good deliverability.
### What's the difference between a bounce and a failure?
A [bounce](#bounced) means the email address is permanently invalid (for example, it does not exist). Bounced addresses are added to your [suppression list](./suppressions). A [failure](#failed) is a temporary delivery issue (for example, full inbox or DKIM misconfiguration). Failures are not suppressed and the email may be retried.
### Why are my emails landing in Promotions instead of Primary?
Landing in [Promotions](#promotions) is not a sign of bad reputation. Gmail and other providers categorize emails based on content and past recipient behavior. To reach the Primary tab, reduce promotional language, personalize content, and encourage recipients to move your emails to Primary.
### What are spam traps and how do they affect me?
[Spam traps](#spam-traps) are addresses set up by inbox providers to catch poor list hygiene. Sending to them can land your domain on a [blocklist](#blocklists). Use confirmed opt-in and remove unengaged recipients. See [Set up a clear opt-in process](./email-reputation-best-practices#set-up-a-clear-opt-in-process).
### Why don't my Gmail spam complaints show up in OneSignal?
Gmail does not provide per-recipient spam complaint feedback to senders. This is an industry-wide limitation. The **Reported spam rate** on the Reputation dashboard only reflects complaints from feedback-loop providers like Yahoo and Outlook.
To monitor Gmail-specific spam rates, [connect Google Postmaster Tools to OneSignal](./google-postmaster-tools) by verifying your domain and adding `mailmonitor@onesignal.com` as a managed user. The Gmail spam rate then appears in [Deliverability insights](./email-deliverability-insights) (**Messages > Email**). You can also view full Gmail charts and domain reputation directly in Postmaster Tools.
### How do I improve my deliverability?
Follow the [email reputation best practices](./email-reputation-best-practices), which covers opt-in, monitoring spam reports, targeting engaged recipients, controlling send frequency, warming up your domain, and list hygiene. If you're sending from a new domain, start with [Email warm-up](./email-warm-up).
### Do I need to warm up before sending large volumes?
Yes. Warm up when you use a new or cold sending domain, especially before you approach **2,000+ emails per day**. Separately, **5,000+ emails per day to Gmail or Yahoo** permanently classifies you as a [bulk sender](#gmail-and-yahoo-bulk-sender-requirements). Start [Email warm-up](./email-warm-up) before either threshold becomes a problem.
## Related pages
Break spam, bounce, open, and fail rates down by inbox provider. Gmail spam rate requires Postmaster Tools.
Actionable steps to build and maintain a healthy sending reputation.
Ramp volume on a new sending domain without hurting deliverability.
Set up SPF, DKIM, and DMARC records for your sending domain.
Connect Postmaster Tools to OneSignal for Gmail spam rate and domain reputation.
Manage your app suppression list of bounced or complained addresses.
Validate addresses during import to reduce bounces.
Diagnose Too old failures and other delivery problems.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
### What helps reputation
* Proper [email authentication](./email-dns-configuration) (SPF, DKIM, DMARC)
* High engagement (e.g., [opens](#opened), [clicks](#clicked), replies)
* Clean, verified lists
* Consistent email sending patterns
### What hurts reputation
* High [spam complaint](#spam-complained) rates. See [Monitor spam reports](./email-reputation-best-practices#monitor-spam-reports-and-complaints).
* High [bounce](#bounced) rates. See [Avoid invalid emails](./email-reputation-best-practices#avoid-invalid-emails).
* Sending to [spam traps](#spam-traps). See [Set up a clear opt-in process](./email-reputation-best-practices#set-up-a-clear-opt-in-process).
### Which spam and bounce limits apply
Use the right threshold for the right system:
| Limit | Source | What it means |
| - | - | - |
| Bounce rate below **5%**; spam complaint rate below **0.08%** | OneSignal [Acceptable Use Policy](https://onesignal.com/aup) | Exceeding these can lead to blocking and AUP enforcement |
| Spam rate below **0.10%**; never reach **0.30%** or higher | [Google's Email Sender Guidelines](https://support.google.com/a/answer/81126?hl=en#spam-rate) | Gmail Postmaster Tools spam rate for your domain |
| Spam complaint rate below **0.3%** | Gmail and Yahoo [bulk sender](#gmail-and-yahoo-bulk-sender-requirements) rules | Required for high-volume senders; aim for Google's 0.10% target |
The OneSignal **Reported spam rate** (Reputation dashboard) excludes Gmail and Apple. For Gmail's rate, [connect Google Postmaster Tools](./google-postmaster-tools). See [How spam rate is calculated](#how-spam-rate-is-calculated).
### Where to monitor reputation
If you use OneSignal Email:
* **Settings > Email > Reputation** for overall bounce and reported spam rates
* **Messages > Email > [Deliverability insights](./email-deliverability-insights)** for the same metrics broken down by inbox provider
If you send through a third-party provider (e.g., SendGrid, Mailchimp, Mailgun), use that provider's dashboard for complaints and bounces.
### How reputation metrics are calculated
* **Bounce rate** = permanent bounces ÷ total sent
* **Reported spam rate** = spam complaints from feedback-loop providers ÷ delivered emails to those providers. Apple and Gmail do not report per-recipient complaints, so their deliveries are excluded from this rate.
See [How spam rate is calculated](#how-spam-rate-is-calculated) for Gmail and Apple details.
### Spam complained
When recipients mark your email as spam, it triggers a spam complaint (also called a spam report).
Common reasons: irrelevant content, excessive frequency, or recipients who did not opt in. Follow the [email reputation best practices](./email-reputation-best-practices) to keep complaints low. Spam complaint events are available in [Event Streams](./event-streams).
#### How spam rate is calculated
A **feedback loop** is how some inbox providers notify senders when a recipient marks mail as spam. Yahoo and Outlook provide feedback loops. Gmail and Apple do not.
The OneSignal **Reported spam rate** is:
**spam complaints from feedback-loop providers ÷ emails delivered to those providers**
Apple and Gmail deliveries are excluded from both the numerator and the denominator. Their complaints never appear in this rate. That is an industry-wide limitation, not a OneSignal limitation. Sustained rates above **0.3%** can hurt placement at major providers. Aim for Google's **0.10%** target when monitoring Gmail in Postmaster Tools. OneSignal's AUP expects complaint rates below **0.08%** on the reported (feedback-loop) rate. See [Which spam and bounce limits apply](#which-spam-and-bounce-limits-apply).
To see **Gmail's** spam rate, [connect Google Postmaster Tools to OneSignal](./google-postmaster-tools): verify your sending domain with Google and add `mailmonitor@onesignal.com` as a managed user. The Gmail figure then appears in [Deliverability insights](./email-deliverability-insights) (**Messages > Email**) next to other providers. Full Gmail charts and domain reputation (High / Medium / Low / Bad) remain in Postmaster Tools.
### Primary
The Primary tab is typically where important and personal mail lands. Primary placement usually signals good reputation and relevance.
### Promotions
The Promotions tab holds promotional or marketing mail. Providers categorize messages using reputation and content signals.
Landing in Promotions is not a sign of bad reputation. Marketing mail often performs better there because recipients expect deals when they open that tab. Gmail also surfaces Promotions intentionally.
To reach Primary more often, reduce heavy promotional language, personalize content, and ask recipients to move your mail to Primary.
### Spam
Emails filtered into spam or junk. Causes include suspicious content, filter triggers, or low sender reputation.
Spam placement usually means reputation trouble. Check bounce and complaint rates against the [limits above](#which-spam-and-bounce-limits-apply). Google expects Postmaster spam rates below **0.10%** and treats **0.30%** as critical. Follow [email reputation best practices](./email-reputation-best-practices). If placement does not look reputation-related, verify DMARC alignment with a tool like [About My Email](https://aboutmy.email/).
## FAQ
### What is the difference between reputation and deliverability?
Reputation is the score inbox providers assign to your sending domain based on past email performance. Deliverability is the outcome: whether your emails reach the inbox, land in spam, or get blocked. A good reputation is the primary driver of good deliverability.
### What's the difference between a bounce and a failure?
A [bounce](#bounced) means the email address is permanently invalid (for example, it does not exist). Bounced addresses are added to your [suppression list](./suppressions). A [failure](#failed) is a temporary delivery issue (for example, full inbox or DKIM misconfiguration). Failures are not suppressed and the email may be retried.
### Why are my emails landing in Promotions instead of Primary?
Landing in [Promotions](#promotions) is not a sign of bad reputation. Gmail and other providers categorize emails based on content and past recipient behavior. To reach the Primary tab, reduce promotional language, personalize content, and encourage recipients to move your emails to Primary.
### What are spam traps and how do they affect me?
[Spam traps](#spam-traps) are addresses set up by inbox providers to catch poor list hygiene. Sending to them can land your domain on a [blocklist](#blocklists). Use confirmed opt-in and remove unengaged recipients. See [Set up a clear opt-in process](./email-reputation-best-practices#set-up-a-clear-opt-in-process).
### Why don't my Gmail spam complaints show up in OneSignal?
Gmail does not provide per-recipient spam complaint feedback to senders. This is an industry-wide limitation. The **Reported spam rate** on the Reputation dashboard only reflects complaints from feedback-loop providers like Yahoo and Outlook.
To monitor Gmail-specific spam rates, [connect Google Postmaster Tools to OneSignal](./google-postmaster-tools) by verifying your domain and adding `mailmonitor@onesignal.com` as a managed user. The Gmail spam rate then appears in [Deliverability insights](./email-deliverability-insights) (**Messages > Email**). You can also view full Gmail charts and domain reputation directly in Postmaster Tools.
### How do I improve my deliverability?
Follow the [email reputation best practices](./email-reputation-best-practices), which covers opt-in, monitoring spam reports, targeting engaged recipients, controlling send frequency, warming up your domain, and list hygiene. If you're sending from a new domain, start with [Email warm-up](./email-warm-up).
### Do I need to warm up before sending large volumes?
Yes. Warm up when you use a new or cold sending domain, especially before you approach **2,000+ emails per day**. Separately, **5,000+ emails per day to Gmail or Yahoo** permanently classifies you as a [bulk sender](#gmail-and-yahoo-bulk-sender-requirements). Start [Email warm-up](./email-warm-up) before either threshold becomes a problem.
## Related pages