Troubleshooting

Mail lands in Gmail Promotions instead of Primary

First — Promotions is not Spam. Mail in Promotions is still delivered, still searchable, still clickable. Opens + clicks from Promotions count as engagement and lift your reputation.

That said, if you're a transactional sender (signup verification, magic link, receipts) you want Primary. Here's how to get there.

What signals Promotions

  • Multiple links in the body (>3)
  • Full-width hero images
  • Bright button-heavy HTML
  • Marketing-y phrasing in the subject (“limited time”, “exclusive”, “free”)
  • Heavy use of multi-column tables
  • Unsubscribe footer + List-Unsubscribe header on a 1:1 transactional message
  • Sender domain's rolling list-membership rate (more campaigns than 1:1 = Promotions)

What signals Primary

  • Plain-text-first or simple HTML (one column)
  • Single CTA link, in body context (not a button block)
  • From a real-looking person name, not no-reply@
  • Reply-to set to a human address (even if the human is your helpdesk)
  • Subject reads like a 1:1 message (“Confirm your account”, not “Welcome to Acme — your free trial starts now!”)
  • Recipient has previously replied to or starred mail from this domain
  • No tracking pixel + no click-redirect wrapping (set tracking_open_disabled: true + tracking_click_disabled: true)

Concrete fixes

For transactional (signup, login, reset)

  1. Send from alice@yourdomain.com with From: “Alice from Acme” <alice@yourdomain.com>
  2. Disable tracking pixel + click tracking
  3. One CTA link maximum
  4. Plain-HTML — no full-width hero, no logo larger than 200px wide
  5. NO unsubscribe footer (transactional is exempt from CAN-SPAM unsub requirements)
  6. Subject: factual, not marketing (e.g. “Confirm your account” not “Welcome — please verify your email”)

For newsletters & campaigns

Newsletters live in Promotions and that's usually fine. To bias toward Primary anyway:

  1. Reply-driving subject lines (“A question for you” not “Top 10 features”)
  2. One main story, max 2 secondary mentions
  3. Plain HTML; no “view in browser” banner
  4. From a person, not a brand: alice@acme.com not news@acme.com

Prime the user

After signup-verification clicks through, show a one-time UI tip:

Heads up — your welcome email might land in your Promotions tab. Drag it to Primaryif you don't want to miss future ones.

That single action by the user is the strongest possible signal to Gmail. Future mail from your domain to that recipient lands in Primary.

Diagnostic — test before you launch

Send the same email to:

  1. A Gmail account you control (check the tab)
  2. A Yahoo account (check spam vs inbox)
  3. An Outlook.com account (check Focused vs Other)
  4. mail-tester.com (target score: ≥9/10)

Then run the body through our spam-score predictorin CI — if quality < 8 the build fails before bad copy ever reaches production.

What NOT to do

  • Don't buy a service that promises “Primary inbox guarantee” — they're selling snake oil. Gmail's tab placement is per-recipient and per-engagement-history; no third-party can override it
  • Don't add “Move me to Primary” instructions to every email — getting Gmail to learn this once is enough
  • Don't spam your domain's reputation by re-sending — once a recipient marks “not promotions”, future sends move; you don't need to retry