Transactional HTML emails break in dark mode more often than they should. A receipt that looks perfect in a browser can turn into unreadable inverted text, invisible buttons, or washed-out logos on Gmail iOS or Apple Mail. The fix is not a magic CSS rule. It is conservative markup: table structure, explicit colors, visible text for every critical fact, and a matching plain-text part. Dark-mode media queries and the color-scheme meta tag are progressive enhancements only.
Why Gmail and other clients invert your carefully designed email
Email clients do not render like browsers. Gmail web often leaves your colors alone. Gmail on iOS and Android may invert light backgrounds or remap colors. Apple Mail and some Outlook surfaces are more likely to honor prefers-color-scheme. None of this is standardized the way web CSS is.
Google’s Gmail CSS support documentation (updated 22 July 2026) lists many standard properties and selected media queries for width, orientation, and resolution. It does not list prefers-color-scheme as a guaranteed feature. Cross-client matrices from early September 2026 still treat dark-mode support as fragmented. Design for the light-mode base first.
Minimum robust HTML structure for transactional mail
Start with a simple table-based skeleton that works even when CSS is stripped or inverted:
Your receipt
Payment received
We charged $49.00 to the card ending in 4242 on 8 Sep 2026.
Download PDF
Key points in this skeleton:
- Explicit background and text colors on every important element.
- Table layout that survives clients that ignore modern CSS.
- Critical facts (amount, date, action URL) live in visible text, not only images.
color-schememeta and a dark media query are present but optional.
What is safer versus what is progressive enhancement
| Technique | Reliability | Notes |
|---|---|---|
| Table-based structure + inline styles | High | Works across Gmail, Apple Mail, Outlook, mobile. |
| Explicit hex colors on text and backgrounds | High | Gives clients a clear starting point even if they invert. |
| Transparent logo or dual light/dark assets | High | Avoid white logos on transparent backgrounds. |
| Plain-text alternative part | High | Required for accessibility and clients that strip HTML. |
meta name="color-scheme" | Medium | Hint only; not universally honored. |
@media (prefers-color-scheme: dark) | Low–Medium | Apple Mail often supports; Gmail mobile is inconsistent. |
| Background images for text | Low | Easily becomes unreadable after inversion. |
Never depend on Flexbox, Grid, or Tailwind classes. Email clients sanitize or ignore them.
Designing logos, buttons, and images for inversion
- Prefer transparent PNGs or SVGs that remain legible on both light and dark backgrounds.
- If you must use a solid logo, host both light and dark versions and switch with media queries where supported.
- Buttons should use solid background colors and high-contrast text. Avoid thin borders that disappear after inversion.
- Never put essential information only inside an image. A password-reset link or order total must appear as live text.
Sending HTML + text through ArawaMail
ArawaMail’s send API (Resend-compatible) accepts both html and text. Provide both. If you omit text, the system derives a plain-text version from the HTML, but an explicit text part is more reliable for deliverability and accessibility.
{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Your receipt for $49.00",
"html": "",
"text": "Payment received\n\nWe charged $49.00 to the card ending in 4242 on 8 Sep 2026.\n\nView full receipt: https://example.com/receipt/abc123\n\nDownload PDF: https://example.com/receipt/abc123.pdf"
}
The sending domain must be registered, allowed by the API key, and have outbound sending activated. ArawaMail does not provide a visual dark-mode preview or automatic CSS inliner. Test in real clients or a seed list.
Related guides:
- Send transactional email from Next.js
- Send email in Laravel
- Stop treating transactional mail as a side project
- Write product email that Gmail can summarize correctly
- The first reader of your email is now an AI
How we analyzed client behavior
We reviewed Google’s Gmail CSS support list (July 2026), current public compatibility matrices for dark-mode media queries, and observed rendering differences between Gmail web, Gmail mobile, Apple Mail, and Outlook. No single hex value or media query guarantees identical appearance. The safe path remains explicit light-mode colors plus progressive enhancement.
FAQ
Does Gmail support prefers-color-scheme?
Gmail’s documented CSS support does not list it as guaranteed. Some Gmail surfaces may honor it; others invert independently. Treat it as enhancement only.
Should I use a pure white background?
A light gray or off-white (#f5f5f5) with dark text is often safer than pure white, but the more important rule is explicit colors on every element that must remain readable.
Can I rely on background images?
No. Text and critical actions must live in HTML text. Background images frequently fail or invert poorly.
Does ArawaMail test dark mode for me?
No. ArawaMail delivers the HTML and text you provide. Use real devices or a multi-client testing service for visual checks.
Build the light-mode version first, keep every important fact in text, ship both HTML and plain text, and treat dark-mode CSS as a nice-to-have. That combination survives the majority of real-world mailboxes in 2026.