chore(docs): Add docs for legacy mail service

trmartin4 · web-flow · commit 3668a445e5e9 · 2025-11-04T11:54:39.000-05:00
* Added docs for legacy mail service.

* Updated namespaces.

* Consolidated under Platform.Mail namespace

* Updated obsolete comment.

* Linting

* Linting

* Replaced documentation in original readme after accidental deletion.
diff --git a/src/Api/AdminConsole/Authorization/AuthorizationHandlerCollectionExtensions.cs b/src/Api/AdminConsole/Authorization/AuthorizationHandlerCollectionExtensions.cs
@@ -12,11 +12,11 @@ public static void AddAdminConsoleAuthorizationHandlers(this IServiceCollection
         services.TryAddScoped<IOrganizationContext, OrganizationContext>();
 
         services.TryAddEnumerable([
-                ServiceDescriptor.Scoped<IAuthorizationHandler, BulkCollectionAuthorizationHandler>(),
-                ServiceDescriptor.Scoped<IAuthorizationHandler, CollectionAuthorizationHandler>(),
-                ServiceDescriptor.Scoped<IAuthorizationHandler, GroupAuthorizationHandler>(),
-                ServiceDescriptor.Scoped<IAuthorizationHandler, OrganizationRequirementHandler>(),
-                ServiceDescriptor.Scoped<IAuthorizationHandler, RecoverAccountAuthorizationHandler>(),
-            ]);
+            ServiceDescriptor.Scoped<IAuthorizationHandler, BulkCollectionAuthorizationHandler>(),
+            ServiceDescriptor.Scoped<IAuthorizationHandler, CollectionAuthorizationHandler>(),
+            ServiceDescriptor.Scoped<IAuthorizationHandler, GroupAuthorizationHandler>(),
+            ServiceDescriptor.Scoped<IAuthorizationHandler, OrganizationRequirementHandler>(),
+            ServiceDescriptor.Scoped<IAuthorizationHandler, RecoverAccountAuthorizationHandler>(),
+        ]);
     }
 }
diff --git a/src/Core/Platform/Mail/Delivery/AmazonSesMailDeliveryService.cs b/src/Core/Platform/Mail/Delivery/AmazonSesMailDeliveryService.cs
@@ -9,7 +9,7 @@
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.Logging;
 
-namespace Bit.Core.Services;
+namespace Bit.Core.Platform.Mail.Delivery;
 
 public class AmazonSesMailDeliveryService : IMailDeliveryService, IDisposable
 {
diff --git a/src/Core/Platform/Mail/Delivery/IMailDeliveryService.cs b/src/Core/Platform/Mail/Delivery/IMailDeliveryService.cs
@@ -1,6 +1,6 @@
 ﻿using Bit.Core.Models.Mail;
 
-namespace Bit.Core.Services;
+namespace Bit.Core.Platform.Mail.Delivery;
 
 public interface IMailDeliveryService
 {
diff --git a/src/Core/Platform/Mail/Delivery/MailKitSmtpMailDeliveryService.cs b/src/Core/Platform/Mail/Delivery/MailKitSmtpMailDeliveryService.cs
@@ -7,7 +7,7 @@
 using Microsoft.Extensions.Logging;
 using MimeKit;
 
-namespace Bit.Core.Services;
+namespace Bit.Core.Platform.Mail.Delivery;
 
 public class MailKitSmtpMailDeliveryService : IMailDeliveryService
 {
diff --git a/src/Core/Platform/Mail/Delivery/MultiServiceMailDeliveryService.cs b/src/Core/Platform/Mail/Delivery/MultiServiceMailDeliveryService.cs
@@ -3,7 +3,7 @@
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.Logging;
 
-namespace Bit.Core.Services;
+namespace Bit.Core.Platform.Mail.Delivery;
 
 public class MultiServiceMailDeliveryService : IMailDeliveryService
 {
diff --git a/src/Core/Platform/Mail/Delivery/NoopMailDeliveryService.cs b/src/Core/Platform/Mail/Delivery/NoopMailDeliveryService.cs
@@ -1,6 +1,6 @@
 ﻿using Bit.Core.Models.Mail;
 
-namespace Bit.Core.Services;
+namespace Bit.Core.Platform.Mail.Delivery;
 
 public class NoopMailDeliveryService : IMailDeliveryService
 {
diff --git a/src/Core/Platform/Mail/Delivery/SendGridMailDeliveryService.cs b/src/Core/Platform/Mail/Delivery/SendGridMailDeliveryService.cs
@@ -6,7 +6,7 @@
 using SendGrid;
 using SendGrid.Helpers.Mail;
 
-namespace Bit.Core.Services;
+namespace Bit.Core.Platform.Mail.Delivery;
 
 public class SendGridMailDeliveryService : IMailDeliveryService, IDisposable
 {
diff --git a/src/Core/Platform/Mail/Enqueuing/AzureQueueMailService.cs b/src/Core/Platform/Mail/Enqueuing/AzureQueueMailService.cs
@@ -1,10 +1,10 @@
 ﻿using Azure.Storage.Queues;
 using Bit.Core.Models.Mail;
+using Bit.Core.Services;
 using Bit.Core.Settings;
 using Bit.Core.Utilities;
 
-namespace Bit.Core.Services;
-
+namespace Bit.Core.Platform.Mail.Enqueuing;
 public class AzureQueueMailService : AzureQueueService<IMailQueueMessage>, IMailEnqueuingService
 {
     public AzureQueueMailService(GlobalSettings globalSettings) : base(
diff --git a/src/Core/Platform/Mail/Enqueuing/BlockingMailQueueService.cs b/src/Core/Platform/Mail/Enqueuing/BlockingMailQueueService.cs
@@ -1,7 +1,6 @@
 ﻿using Bit.Core.Models.Mail;
 
-namespace Bit.Core.Services;
-
+namespace Bit.Core.Platform.Mail.Enqueuing;
 public class BlockingMailEnqueuingService : IMailEnqueuingService
 {
     public async Task EnqueueAsync(IMailQueueMessage message, Func<IMailQueueMessage, Task> fallback)
diff --git a/src/Core/Platform/Mail/Enqueuing/IMailEnqueuingService.cs b/src/Core/Platform/Mail/Enqueuing/IMailEnqueuingService.cs
@@ -1,6 +1,6 @@
 ﻿using Bit.Core.Models.Mail;
 
-namespace Bit.Core.Services;
+namespace Bit.Core.Platform.Mail.Enqueuing;
 
 public interface IMailEnqueuingService
 {
diff --git a/src/Core/Platform/Mail/HandlebarsMailService.cs b/src/Core/Platform/Mail/HandlebarsMailService.cs
@@ -19,6 +19,8 @@
 using Bit.Core.Models.Mail.Billing;
 using Bit.Core.Models.Mail.FamiliesForEnterprise;
 using Bit.Core.Models.Mail.Provider;
+using Bit.Core.Platform.Mail.Delivery;
+using Bit.Core.Platform.Mail.Enqueuing;
 using Bit.Core.SecretsManager.Models.Mail;
 using Bit.Core.Settings;
 using Bit.Core.Utilities;
@@ -28,8 +30,9 @@
 using Microsoft.Extensions.Caching.Distributed;
 using Microsoft.Extensions.Logging;
 
-namespace Bit.Core.Services;
+namespace Bit.Core.Services.Mail;
 
+[Obsolete("The IMailService has been deprecated in favor of the IMailer. All new emails should be sent with an IMailer implementation.")]
 public class HandlebarsMailService : IMailService
 {
     private const string Namespace = "Bit.Core.MailTemplates.Handlebars";
diff --git a/src/Core/Platform/Mail/IMailService.cs b/src/Core/Platform/Mail/IMailService.cs
@@ -12,6 +12,7 @@
 
 namespace Bit.Core.Services;
 
+[Obsolete("The IMailService has been deprecated in favor of the IMailer. All new emails should be sent with an IMailer implementation.")]
 public interface IMailService
 {
     Task SendWelcomeEmailAsync(User user);
diff --git a/src/Core/Platform/Mail/Mailer/BaseMail.cs b/src/Core/Platform/Mail/Mailer/BaseMail.cs
@@ -1,4 +1,4 @@
-﻿namespace Bit.Core.Platform.Mailer;
+﻿namespace Bit.Core.Platform.Mail.Mailer;
 
 #nullable enable
 
diff --git a/src/Core/Platform/Mail/Mailer/HandlebarMailRenderer.cs b/src/Core/Platform/Mail/Mailer/HandlebarMailRenderer.cs
@@ -3,8 +3,7 @@
 using System.Reflection;
 using HandlebarsDotNet;
 
-namespace Bit.Core.Platform.Mailer;
-
+namespace Bit.Core.Platform.Mail.Mailer;
 public class HandlebarMailRenderer : IMailRenderer
 {
     /// <summary>
diff --git a/src/Core/Platform/Mail/Mailer/IMailRenderer.cs b/src/Core/Platform/Mail/Mailer/IMailRenderer.cs
@@ -1,5 +1,5 @@
 ﻿#nullable enable
-namespace Bit.Core.Platform.Mailer;
+namespace Bit.Core.Platform.Mail.Mailer;
 
 public interface IMailRenderer
 {
diff --git a/src/Core/Platform/Mail/Mailer/IMailer.cs b/src/Core/Platform/Mail/Mailer/IMailer.cs
@@ -1,4 +1,4 @@
-﻿namespace Bit.Core.Platform.Mailer;
+﻿namespace Bit.Core.Platform.Mail.Mailer;
 
 #nullable enable
 
diff --git a/src/Core/Platform/Mail/Mailer/Mailer.cs b/src/Core/Platform/Mail/Mailer/Mailer.cs
@@ -1,7 +1,7 @@
 ﻿using Bit.Core.Models.Mail;
-using Bit.Core.Services;
+using Bit.Core.Platform.Mail.Delivery;
 
-namespace Bit.Core.Platform.Mailer;
+namespace Bit.Core.Platform.Mail.Mailer;
 
 #nullable enable
 
diff --git a/src/Core/Platform/Mail/Mailer/MailerServiceCollectionExtensions.cs b/src/Core/Platform/Mail/Mailer/MailerServiceCollectionExtensions.cs
@@ -1,7 +1,7 @@
 ﻿using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 
-namespace Bit.Core.Platform.Mailer;
+namespace Bit.Core.Platform.Mail.Mailer;
 
 #nullable enable
 
diff --git a/src/Core/Platform/Mail/NoopMailService.cs b/src/Core/Platform/Mail/NoopMailService.cs
@@ -13,6 +13,7 @@
 
 namespace Bit.Core.Services;
 
+[Obsolete("The IMailService has been deprecated in favor of the IMailer. All new emails should be sent with an IMailer implementation.")]
 public class NoopMailService : IMailService
 {
     public Task SendChangeEmailAlreadyExistsEmailAsync(string fromEmail, string toEmail)
diff --git a/src/Core/Platform/Mail/README.md b/src/Core/Platform/Mail/README.md
@@ -1,9 +1,16 @@
-# Mailer
+# Mail Services
+## `MailService`
+
+The `MailService` and its implementation in `HandlebarsMailService` has been deprecated in favor of the `Mailer` implementation.
+
+New emails should be implemented using [MJML](../../MailTemplates/README.md) and the `Mailer`.
+
+## `Mailer`
 
 The Mailer feature provides a structured, type-safe approach to sending emails in the Bitwarden server application. It
 uses Handlebars templates to render both HTML and plain text email content.
 
-## Architecture
+### Architecture
 
 The Mailer system consists of four main components:
 
@@ -12,17 +19,17 @@ The Mailer system consists of four main components:
 3. **BaseMailView** - Abstract base class for email template view models
 4. **IMailRenderer** - Internal interface for rendering templates (implemented by `HandlebarMailRenderer`)
 
-## How To Use
+### How To Use
 
 1. Define a view model that inherits from `BaseMailView` with properties for template data
 2. Create Handlebars templates (`.html.hbs` and `.text.hbs`) as embedded resources, preferably using the MJML pipeline,
    `/src/Core/MailTemplates/Mjml`.
 3. Define an email class that inherits from `BaseMail<TView>` with metadata like subject
 4. Use `IMailer.SendEmail()` to render and send the email
 
-## Creating a New Email
+### Creating a New Email
 
-### Step 1: Define the Email & View Model
+#### Step 1: Define the Email & View Model
 
 Create a class that inherits from `BaseMailView`:
 
@@ -43,7 +50,7 @@ public class WelcomeEmail : BaseMail<WelcomeEmailView>
 }
 ```
 
-### Step 2: Create Handlebars Templates
+#### Step 2: Create Handlebars Templates
 
 Create two template files as embedded resources next to your view model. **Important**: The file names must be located
 directly next to the `ViewClass` and match the name of the view.
@@ -80,7 +87,7 @@ Activate your account: {{ ActivationUrl }}
 </ItemGroup>
 ```
 
-### Step 3: Send the Email
+#### Step 3: Send the Email
 
 Inject `IMailer` and send the email, this may be done in a service, command or some other application layer.
 
@@ -111,9 +118,9 @@ public class SomeService
 }
 ```
 
-## Advanced Features
+### Advanced Features
 
-### Multiple Recipients
+#### Multiple Recipients
 
 Send to multiple recipients by providing multiple email addresses:
 
@@ -125,7 +132,7 @@ var mail = new WelcomeEmail
 };
 ```
 
-### Bypass Suppression List
+#### Bypass Suppression List
 
 For critical emails like account recovery or email OTP, you can bypass the suppression list:
 
@@ -139,7 +146,7 @@ public class PasswordResetEmail : BaseMail<PasswordResetEmailView>
 
 **Warning**: Only use `IgnoreSuppressList = true` for critical account recovery or authentication emails.
 
-### Email Categories
+#### Email Categories
 
 Optionally categorize emails for processing at the upstream email delivery service:
 
@@ -151,7 +158,7 @@ public class MarketingEmail : BaseMail<MarketingEmailView>
 }
 ```
 
-## Built-in View Properties
+### Built-in View Properties
 
 All view models inherit from `BaseMailView`, which provides:
 
@@ -162,7 +169,7 @@ All view models inherit from `BaseMailView`, which provides:
 <footer>&copy; {{ CurrentYear }} Bitwarden Inc.</footer>
 ```
 
-## Template Naming Convention
+### Template Naming Convention
 
 Templates must follow this naming convention:
 
@@ -193,8 +200,14 @@ services.TryAddSingleton<IMailRenderer, HandlebarMailRenderer>();
 services.TryAddSingleton<IMailer, Mailer>();
 ```
 
-## Performance Notes
+### Performance Notes
 
 - **Template caching** - `HandlebarMailRenderer` automatically caches compiled templates
 - **Lazy initialization** - Handlebars is initialized only when first needed
 - **Thread-safe** - The renderer is thread-safe for concurrent email rendering
+
+# Overriding email templates from disk
+
+The mail services support loading the mail template from disk. This is intended to be used by self-hosted customers who want to modify their email appearance. These overrides are not intended to be used during local development, as any changes there would not be reflected in the templates used in a normal deployment configuration.
+
+Any customer using this override has worked with Bitwarden support on an approved implementation and has acknowledged that they are responsible for reacting to any changes made to the templates as a part of the Bitwarden development process. This includes, but is not limited to, changes in Handlebars property names, removal of properties from the `ViewModel` classes, and changes in template names.  **Bitwarden is not responsible for maintaining backward compatibility between releases in order to support any overridden emails.**
diff --git a/src/SharedWeb/Utilities/ServiceCollectionExtensions.cs b/src/SharedWeb/Utilities/ServiceCollectionExtensions.cs
@@ -38,7 +38,9 @@
 using Bit.Core.NotificationCenter;
 using Bit.Core.OrganizationFeatures;
 using Bit.Core.Platform;
-using Bit.Core.Platform.Mailer;
+using Bit.Core.Platform.Mail.Delivery;
+using Bit.Core.Platform.Mail.Enqueuing;
+using Bit.Core.Platform.Mail.Mailer;
 using Bit.Core.Platform.Push;
 using Bit.Core.Platform.PushRegistration.Internal;
 using Bit.Core.Repositories;
@@ -47,6 +49,7 @@
 using Bit.Core.SecretsManager.Repositories.Noop;
 using Bit.Core.Services;
 using Bit.Core.Services.Implementations;
+using Bit.Core.Services.Mail;
 using Bit.Core.Settings;
 using Bit.Core.Tokens;
 using Bit.Core.Tools.ImportFeatures;
diff --git a/test/Core.IntegrationTest/MailKitSmtpMailDeliveryServiceTests.cs b/test/Core.IntegrationTest/MailKitSmtpMailDeliveryServiceTests.cs
@@ -1,7 +1,7 @@
 ﻿using System.Security.Cryptography;
 using System.Security.Cryptography.X509Certificates;
 using Bit.Core.Models.Mail;
-using Bit.Core.Services;
+using Bit.Core.Platform.Mail.Delivery;
 using Bit.Core.Settings;
 using MailKit.Security;
 using Microsoft.Extensions.Logging;
diff --git a/test/Core.Test/Platform/Mailer/HandlebarMailRendererTests.cs b/test/Core.Test/Platform/Mailer/HandlebarMailRendererTests.cs
@@ -1,4 +1,4 @@
-﻿using Bit.Core.Platform.Mailer;
+﻿using Bit.Core.Platform.Mail.Mailer;
 using Bit.Core.Test.Platform.Mailer.TestMail;
 using Xunit;
 
diff --git a/test/Core.Test/Platform/Mailer/MailerTest.cs b/test/Core.Test/Platform/Mailer/MailerTest.cs
@@ -1,19 +1,18 @@
 ﻿using Bit.Core.Models.Mail;
-using Bit.Core.Platform.Mailer;
-using Bit.Core.Services;
+using Bit.Core.Platform.Mail.Delivery;
+using Bit.Core.Platform.Mail.Mailer;
 using Bit.Core.Test.Platform.Mailer.TestMail;
 using NSubstitute;
 using Xunit;
 
 namespace Bit.Core.Test.Platform.Mailer;
-
 public class MailerTest
 {
     [Fact]
     public async Task SendEmailAsync()
     {
         var deliveryService = Substitute.For<IMailDeliveryService>();
-        var mailer = new Core.Platform.Mailer.Mailer(new HandlebarMailRenderer(), deliveryService);
+        var mailer = new Core.Platform.Mail.Mailer.Mailer(new HandlebarMailRenderer(), deliveryService);
 
         var mail = new TestMail.TestMail()
         {
diff --git a/test/Core.Test/Platform/Mailer/TestMail/TestMailView.cs b/test/Core.Test/Platform/Mailer/TestMail/TestMailView.cs
@@ -1,4 +1,4 @@
-﻿using Bit.Core.Platform.Mailer;
+﻿using Bit.Core.Platform.Mail.Mailer;
 
 namespace Bit.Core.Test.Platform.Mailer.TestMail;
 
diff --git a/test/Core.Test/Services/AmazonSesMailDeliveryServiceTests.cs b/test/Core.Test/Services/AmazonSesMailDeliveryServiceTests.cs
@@ -1,7 +1,7 @@
 ﻿using Amazon.SimpleEmail;
 using Amazon.SimpleEmail.Model;
 using Bit.Core.Models.Mail;
-using Bit.Core.Services;
+using Bit.Core.Platform.Mail.Delivery;
 using Bit.Core.Settings;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.Logging;
diff --git a/test/Core.Test/Services/HandlebarsMailServiceTests.cs b/test/Core.Test/Services/HandlebarsMailServiceTests.cs
@@ -6,7 +6,10 @@
 using Bit.Core.Auth.Models.Business;
 using Bit.Core.Entities;
 using Bit.Core.Models.Mail;
+using Bit.Core.Platform.Mail.Delivery;
+using Bit.Core.Platform.Mail.Enqueuing;
 using Bit.Core.Services;
+using Bit.Core.Services.Mail;
 using Bit.Core.Settings;
 using Microsoft.Extensions.Caching.Distributed;
 using Microsoft.Extensions.Logging;
diff --git a/test/Core.Test/Services/MailKitSmtpMailDeliveryServiceTests.cs b/test/Core.Test/Services/MailKitSmtpMailDeliveryServiceTests.cs
@@ -1,4 +1,4 @@
-﻿using Bit.Core.Services;
+﻿using Bit.Core.Platform.Mail.Delivery;
 using Bit.Core.Settings;
 using Microsoft.Extensions.Logging;
 using NSubstitute;
diff --git a/test/Core.Test/Services/SendGridMailDeliveryServiceTests.cs b/test/Core.Test/Services/SendGridMailDeliveryServiceTests.cs
diff --git a/test/IntegrationTestCommon/Factories/WebApplicationFactoryBase.cs b/test/IntegrationTestCommon/Factories/WebApplicationFactoryBase.cs

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`using Microsoft.AspNetCore.Hosting;`
`10`	`10`	`using Microsoft.Extensions.Logging;`
`11`	`11`
`12`		`-namespace Bit.Core.Services;`
	`12`	`+namespace Bit.Core.Platform.Mail.Delivery;`
`13`	`13`
`14`	`14`	`public class AmazonSesMailDeliveryService : IMailDeliveryService, IDisposable`
`15`	`15`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`using Bit.Core.Models.Mail;`
`2`	`2`
`3`		`-namespace Bit.Core.Services;`
	`3`	`+namespace Bit.Core.Platform.Mail.Delivery;`
`4`	`4`
`5`	`5`	`public interface IMailDeliveryService`
`6`	`6`	`{`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`using Microsoft.Extensions.Logging;`
`8`	`8`	`using MimeKit;`
`9`	`9`
`10`		`-namespace Bit.Core.Services;`
	`10`	`+namespace Bit.Core.Platform.Mail.Delivery;`
`11`	`11`
`12`	`12`	`public class MailKitSmtpMailDeliveryService : IMailDeliveryService`
`13`	`13`	`{`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@`
`3`	`3`	`using Microsoft.AspNetCore.Hosting;`
`4`	`4`	`using Microsoft.Extensions.Logging;`
`5`	`5`
`6`		`-namespace Bit.Core.Services;`
	`6`	`+namespace Bit.Core.Platform.Mail.Delivery;`
`7`	`7`
`8`	`8`	`public class MultiServiceMailDeliveryService : IMailDeliveryService`
`9`	`9`	`{`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`using SendGrid;`
`7`	`7`	`using SendGrid.Helpers.Mail;`
`8`	`8`
`9`		`-namespace Bit.Core.Services;`
	`9`	`+namespace Bit.Core.Platform.Mail.Delivery;`
`10`	`10`
`11`	`11`	`public class SendGridMailDeliveryService : IMailDeliveryService, IDisposable`
`12`	`12`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,6 @@`
`1`	`1`	`using Bit.Core.Models.Mail;`
`2`	`2`
`3`		`-namespace Bit.Core.Services;`
`4`		`-`
	`3`	`+namespace Bit.Core.Platform.Mail.Enqueuing;`
`5`	`4`	`public class BlockingMailEnqueuingService : IMailEnqueuingService`
`6`	`5`	`{`
`7`	`6`	`public async Task EnqueueAsync(IMailQueueMessage message, Func<IMailQueueMessage, Task> fallback)`