Two Reproducible Issues with GitHub Notification Emails in Apple Mail

[btrazzini]

🏷️ Discussion Type

Product Feedback

💬 Feature/Topic Area

Other

Body

I would like to report two reproducible issues I have been experiencing with GitHub notification emails when viewed in Apple Mail. I have analyzed the raw email sources and can provide specific technical evidence for both.

---

1. Thread Ordering: Identical Timestamps Cause Messages to Appear Out of Order

When a Pull Request is opened and a review is requested simultaneously, GitHub dispatches both notifications in parallel — from different SMTP nodes — within the same second. Both messages end up with the exact same value in the Date header.

Here is a representative example:

• Email 1 (PR opened):

  • Date: Fri, 19 Jun 2026 12:04:45 -0700
  • Message-ID: <org/repository/pull/NNN@github.com>

• Email 2 (review requested):

  • Date: Fri, 19 Jun 2026 12:04:45 -0700
  • Message-ID: <org/repository/pull/NNN/issue_event/XXXXXXXXX@github.com>
  • In-Reply-To: <org/repository/pull/NNN@github.com>

Even though Email 2 correctly declares In-Reply-To pointing to Email 1, Apple Mail uses the Date header as the primary sort key within a thread. When two messages share the same timestamp down to the second, the tiebreaker is undefined and Apple Mail ends up displaying the reply before the original message.

The X-Received header from Gmail shows the actual arrival difference was only ~256 milliseconds, which is invisible at the Date header's one-second resolution.

A simple fix would be to ensure that related but distinct notifications dispatched in the same event batch carry Date values that differ by at least one second, so that mail clients can establish a reliable sort order.

---

2. Dark Mode: Inline Flexbox Layout Disables Apple Mail's Automatic Inversion

GitHub uses two different HTML templates for different notification types, and only one of them renders correctly in Apple Mail's Dark Mode.

Template A — system events (e.g., "review requested"):

<div class="email-fragment">
  <a class="user-mention">@username</a> requested your review on: ...
</div>

This renders correctly in Dark Mode. Apple Mail applies its automatic color inversion to the entire message.

Template B — user comments (e.g., a comment left on a PR):

<div style="display: flex; flex-wrap: wrap; white-space: pre-wrap; align-items: center;">
  <img style="border-radius:50%; margin-right: 4px;" src="avatar-url" />
  <strong>username</strong> left a comment ...
</div>
<p dir="auto">Comment body here.</p>

This fails in Dark Mode. The comment body appears with light-mode colors on a dark background, making it difficult to read.

The root cause is Apple Mail's Dark Mode heuristic: when it encounters a container with complex inline layout styles (display: flex combined with white-space: pre-wrap and align-items), it treats the block as a manually controlled UI component and disables automatic color inversion for that block and its siblings in the same context.

Additionally, the footer paragraph present in all GitHub notification emails contains a hardcoded inline color:

<p style="font-size:small; -webkit-text-size-adjust:none; color:#666;">...</p>

The #666 value is legible on white backgrounds but becomes low-contrast on dark backgrounds, since inline styles are not overridden by Apple Mail's inversion engine.

The two changes that would resolve this:

1. Replace the avatar/comment container's inline display: flex with a class-based or table-based layout, which Apple Mail's Dark Mode engine handles gracefully.
2. Add a <style> block with a @media (prefers-color-scheme: dark) rule to adjust text colors for dark environments, instead of relying solely on inline color values.

---

I understand that supporting every email client's quirks is a significant engineering effort, and I genuinely appreciate the quality of GitHub's notification system overall. I am sharing these findings because I have the raw headers and HTML to back them up, and I hope they are useful for your team.

Thank you for your time.