Message importance

CHANGELOG.md

@@ -1,3 +1,7 @@
+# Unreleased
+
+- Added support for setting a message importance (`Importance`, `X-Priority`) #15
+
 # 2.2.0
 
 - Added some badges to the README

TRENZ.Lib.RazorMail.Core/Models/MailHeaderCollection.cs

@@ -37,11 +37,22 @@
     /// </summary>
     public const string FromKey = "From";
 
+    /// <summary>
+    /// The key for the "Importance" header.
+    /// </summary>
+    public const string ImportanceKey = "Importance";
+
     /// <summary>
     /// The keys for the mail addresses in the collection.
     /// </summary>
     public static readonly string[] AddressKeys = [ToKey, CcKey, BccKey, ReplyToKey, FromKey];
 
+    /// <summary>
+    /// Keys for headers that the <see cref="BaseSmtpMailClient"/>
+    /// implementation must set explicitly.
+    /// </summary>
+    public static readonly string[] SpecificHandledHeaderKeys = [..AddressKeys, ImportanceKey];
+
     /// <summary>
     /// The recipients of the mail message.
     /// </summary>
@@ -99,6 +110,18 @@
         }
     }
 
+    public MailImportance Importance
+    {
+        get
+        {
+            if (TryGetValue(ImportanceKey, out var value) && value is MailImportance importance)
+                return importance;
+
+            return MailImportance.Normal;
+        }
+        set => this[ImportanceKey] = value;
+    }
+
     private IEnumerable<MailAddress> GetAddresses(string key)
     {
         if (!TryGetValue(key, out var value) || value is not IEnumerable<MailAddress> addresses)
@@ -161,10 +184,18 @@
     /// <summary>
     /// Gets the headers that are not mail addresses and therefore have no getter/setter.
     /// </summary>
-    public IReadOnlyDictionary<string, object> NonAddressHeaders => this
+    [Obsolete("This will be removed in a future version.")]
+    private IReadOnlyDictionary<string, object> NonAddressHeaders => this
         .ExceptBy(AddressKeys, x => x.Key)
         .ToDictionary(x => x.Key, x => x.Value);
 
+    /// <summary>
+    /// Gets the headers that the <see cref="BaseSmtpMailClient"/> implementation should just iterate over.
+    /// </summary>
+    public IReadOnlyDictionary<string, object> NonSpecificHandledHeaders => this
+        .ExceptBy(SpecificHandledHeaderKeys, x => x.Key)
+        .ToDictionary(x => x.Key, x => x.Value);
+
     /// <summary>
     /// Appends <paramref name="other"/> to this collection without overwriting existing values.
     /// </summary>
@@ -179,7 +210,7 @@
         AddBlindCarbonCopy(other.BlindCarbonCopy);
         AddReplyTo(other.ReplyTo);
 
         foreach (var (key, value) in other.NonAddressHeaders)
             if (!ContainsKey(key))
                 this[key] = value;
 

TRENZ.Lib.RazorMail.Core/Models/MailImportance.cs

@@ -0,0 +1,43 @@
+namespace TRENZ.Lib.RazorMail.Models;
+
+/// <summary>
+/// Specifies the urgency in which the mail should be delivered.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This sets both the <c>Importance</c> and <c>X-Priority</c> headers, for
+/// broad compatibility.
+/// </para>
+/// <para>
+/// RFC 2156 (https://www.rfc-editor.org/rfc/rfc2156) defines <c>Importance</c>
+/// values <c>low</c>, <c>normal</c>, and <c>high</c>. <c>X-Priority</c> is
+/// proprietary, and documented at Microsoft:
+/// https://learn.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-oxcmail/2bb19f1b-b35e-4966-b1cb-1afd044e83ab,
+/// and takes the values <c>1</c> (highest) through <c>5</c> (lowest).
+/// </para>
+/// </remarks>
+public enum MailImportance
+{
+    High = 1,
+    Normal = 3,
+    Low = 5
+}
+
+public static class MailImportanceExtensions
+{
+    public static string ToImportanceHeaderValue(this MailImportance importance)
+        => importance switch
+        {
+            MailImportance.High => "high",
+            MailImportance.Low => "low",
+            _ => "normal",
+        };
+
+    public static string ToXPriorityHeaderValue(this MailImportance importance)
+        => importance switch
+        {
+            MailImportance.High => "2",
+            MailImportance.Low => "4",
+            _ => "3",
+        };
+}

TRENZ.Lib.RazorMail.MailKit/Extensions/MailMessageExtensions.cs

@@ -2,6 +2,8 @@
 
 using MimeKit;
 
+using TRENZ.Lib.RazorMail.Models;
+
 namespace TRENZ.Lib.RazorMail.MailKit.Extensions;
 
 using RazorMailMessage = Models.MailMessage;
@@ -36,7 +38,21 @@ private static void SetMailHeaders(RazorMailMessage razorMessage, IMailKitMailMe
         mailMessage.Bcc.AddRange(razorMessage.Headers.BlindCarbonCopy.Select(x => x.ToMailboxAddress()));
         mailMessage.ReplyTo.AddRange(razorMessage.Headers.ReplyTo.Select(x => x.ToMailboxAddress()));
 
-        foreach (var (name, value) in razorMessage.Headers.NonAddressHeaders)
+        mailMessage.Importance = razorMessage.Headers.Importance switch
+        {
+            MailImportance.Low => MessageImportance.Low,
+            MailImportance.High => MessageImportance.High,
+            _ => MessageImportance.Normal
+        };
+
+        mailMessage.XPriority = razorMessage.Headers.Importance switch
+        {
+            MailImportance.Low => XMessagePriority.Low,
+            MailImportance.High => XMessagePriority.High,
+            _ => XMessagePriority.Normal
+        };
+
+        foreach (var (name, value) in razorMessage.Headers.NonSpecificHandledHeaders)
         {
             mailMessage.Headers.Add(name, value.ToString());
         }
@@ -61,4 +77,4 @@ private static void SetMailContent(RazorMailMessage razorMessage, IMailKitMailMe
 
         mailMessage.Body = bodyBuilder.ToMessageBody();
     }
-}
+}

TRENZ.Lib.RazorMail.SystemNet/Extensions/SystemNetMailMessageExtensions.cs

@@ -2,6 +2,8 @@
 
 using JetBrains.Annotations;
 
+using TRENZ.Lib.RazorMail.Models;
+
 using RazorMailMessage = TRENZ.Lib.RazorMail.Models.MailMessage;
 using SystemNetMailMessage = System.Net.Mail.MailMessage;
 
@@ -46,8 +48,12 @@ private static void SetMailHeaders(RazorMailMessage razorMessage, SystemNetMailM
 
         foreach (var item in razorMessage.Headers.ReplyTo)
             systemNetMessage.ReplyToList.Add(item.ToMailAddress());
+
+        systemNetMessage.Headers["Importance"] = razorMessage.Headers.Importance.ToImportanceHeaderValue();
+
+        systemNetMessage.Headers["X-Priority"] = razorMessage.Headers.Importance.ToXPriorityHeaderValue();
 
-        foreach (var (name, value) in razorMessage.Headers.NonAddressHeaders)
+        foreach (var (name, value) in razorMessage.Headers.NonSpecificHandledHeaders)
         {
             systemNetMessage.Headers.Add(name, value.ToString());
         }