Skip to content

Conversation

@tkaufmann
Copy link
Contributor

Summary

This PR implements automatic generation of RFC 5322 compliant Message-ID headers for all email notifications sent by diun.

Currently, diun email notifications do not include a Message-ID header, which can cause issues with:

  • Email threading and tracking in mail clients
  • Spam filtering systems
  • RFC 5322 compliance

Changes

  • New function generateMessageID() in internal/notif/mail/client.go:

    • Generates unique Message-IDs using nanosecond timestamps for high resolution
    • Includes 8 bytes of cryptographically secure random data (hex encoded)
    • Format: <timestamp.randomhex@domain>
    • Domain is taken from LocalName config if set, otherwise falls back to Host
  • Integration in Send() method:

    • Message-ID is generated before sending each email
    • Header is set using mailMessage.SetHeader("Message-ID", messageID)
  • Comprehensive unit tests in internal/notif/mail/client_test.go:

    • TestGenerateMessageID: Validates format with LocalName and Host fallback
    • TestGenerateMessageID_Uniqueness: Verifies uniqueness across 1000 iterations
    • TestGenerateMessageID_Format: Validates RFC 5322 format compliance

Benefits

✅ Improves email threading and tracking in mail clients
✅ Enhances spam filter compatibility
✅ Ensures RFC 5322 compliance for all outgoing notifications
✅ Each message gets a globally unique identifier

Testing

All tests pass successfully:

=== RUN   TestGenerateMessageID
=== RUN   TestGenerateMessageID/with_LocalName
=== RUN   TestGenerateMessageID/fallback_to_Host
--- PASS: TestGenerateMessageID (0.00s)
=== RUN   TestGenerateMessageID_Uniqueness
--- PASS: TestGenerateMessageID_Uniqueness (0.00s)
=== RUN   TestGenerateMessageID_Format
--- PASS: TestGenerateMessageID_Format (0.00s)
PASS
coverage: 16.4% of statements
ok  	github.com/crazy-max/diun/v4/internal/notif/mail

Tested with: docker buildx bake test

Implementation Details

The Message-ID generation follows RFC 5322 best practices:

  • Uses highest-resolution clock (nanoseconds) for timestamp component
  • Includes cryptographically secure randomness (64 bits) for uniqueness
  • Properly formatted as <local-part@domain>
  • Domain component ensures global uniqueness guarantee

Example generated Message-ID:

<1733837213123456789.a1b2c3d4e5f6a7b8@mail.example.com>

@tkaufmann tkaufmann requested a review from crazy-max as a code owner December 10, 2025 13:15
Copy link
Owner

@crazy-max crazy-max left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you squash your commits please?

Otherwise LGTM thanks

Implements unique Message-ID generation for email notifications to enhance
email threading, tracking, and spam filter compatibility.

Features:
- Generates RFC 5322 compliant Message-ID headers
- Uses nanosecond timestamps for high-resolution uniqueness
- Includes 64 bits of cryptographically secure random data
- Format: <timestamp.randomhex@domain>
- Domain derived from LocalName config, falling back to Host

Tests:
- Validates RFC 5322 format compliance
- Ensures uniqueness across 1,000 iterations
- Verifies correct domain usage and structure
@tkaufmann tkaufmann force-pushed the feature/add-message-id-header branch from 8deffe2 to b44181f Compare December 19, 2025 13:19
@crazy-max crazy-max merged commit 4474ba0 into crazy-max:master Dec 22, 2025
43 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants