Before troubleshooting, review our Email Setup and Email Deliverability guides. These cover the most common causes of email issues.
Setup issues
Most setup problems come from incorrect DNS records or limitations from your Email Service Provider (ESP).Verify DNS records
- Open your DNS provider.
- Confirm that SPF, DKIM, and MX records match our Email DNS Configuration guide.
- Allow up to 24 hours for DNS changes to propagate.
If DNS records are misconfigured, emails may fail to send, bounce, or be marked as spam.
Monthly send limits (non-OneSignal ESPs)
If you use SendGrid, Mailchimp, or Mailgun directly (not via OneSignal Email), your sending volume is limited by your ESP plan.Check your provider’s logs:
Too many DNS lookups
When testing SPF records with tools like URI test, you may see:
Too many DNS lookups
Multiple TXT records for sender domain
You can only have one SPF record for your sending domain.Check with WhatsMyDNS TXT lookup to confirm you do not have multiple entries.
Deliverability issues
Deliverability problems include slow sends, spam folder placement, and email bounces.Delayed emails
If your sending domain is new or has low reputation, ISPs (Gmail, Outlook, Yahoo) may delay delivery. This is called rate limiting or greylisting. When looking at your Email Message Reports, you can check the details of how long it took us to send the message.
Email sent from OneSignal in less than 3 seconds
Follow our Email Reputation Best Practices to speed up delivery.
Emails landing in spam
The most common cause is poor sender reputation. Follow our Email Deliverability guide. If you are using a third-party ESP, see:Sending & receiving from the same domain
A single domain cannot use the same MX records for sending and receiving mail simultaneously. If you want to send from@yourdomain.com
and also receive on the same domain:
- Keep your sending DNS with OneSignal.
- Point your MX records to your inbound email provider (e.g., Google Workspace MX records).
Suppression lists
If an address unsubscribed or marked you as spam, your ESP will suppress sends to it.To resubscribe:
- Go to Audience > Subscriptions in OneSignal.
- Search for the email address.
- Click Unsubscribe from Email (if subscribed) then Resubscribe to Email.
- Send a test email to confirm.
Apple Private Relay
If you send to@privaterelay.appleid.com
addresses, you must verify your sending domain in your Apple Developer account.Unverified domains will result in dropped emails.
API key too restrictive
If using SendGrid or Mailchimp, ensure your API key has the minimum required permissions.Email design
These are problems inside the email content itself.Links not working
Usually caused by missing or incorrect CNAME configuration.If using a third-party ESP, follow their tracking domain setup.
Buttons not clickable
- Ensure the URL is correct and starts with
https://
. - Avoid testing from your spam folder—some email clients block links there.
Adding images to preheader
Gmail supports promotional images in preheaders (deal annotations, product carousels).See Gmail Developer Portal for setup.