[Feature] Add Mailpit module

Directory.Packages.props

@@ -67,6 +67,7 @@
         <PackageVersion Include="Keycloak.Net.Core" Version="1.0.20"/>
         <PackageVersion Include="KubernetesClient" Version="17.0.14"/>
         <PackageVersion Include="KurrentDB.Client" Version="1.4.0"/>
+        <PackageVersion Include="MailKitLite" Version="4.17.0"/>
         <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.32.1"/>
         <PackageVersion Include="Microsoft.Azure.Kusto.Data" Version="12.2.8"/>
         <PackageVersion Include="Microsoft.Data.SqlClient" Version="5.2.2"/>

Testcontainers.slnx

@@ -48,6 +48,7 @@
         <Project Path="src/Testcontainers.Kusto/Testcontainers.Kusto.csproj"/>
         <Project Path="src/Testcontainers.LocalStack/Testcontainers.LocalStack.csproj"/>
         <Project Path="src/Testcontainers.LowkeyVault/Testcontainers.LowkeyVault.csproj"/>
+        <Project Path="src/Testcontainers.Mailpit/Testcontainers.Mailpit.csproj"/>
         <Project Path="src/Testcontainers.MariaDb/Testcontainers.MariaDb.csproj"/>
         <Project Path="src/Testcontainers.Milvus/Testcontainers.Milvus.csproj"/>
         <Project Path="src/Testcontainers.Minio/Testcontainers.Minio.csproj"/>
@@ -116,6 +117,7 @@
         <Project Path="tests/Testcontainers.Kusto.Tests/Testcontainers.Kusto.Tests.csproj"/>
         <Project Path="tests/Testcontainers.LocalStack.Tests/Testcontainers.LocalStack.Tests.csproj"/>
         <Project Path="tests/Testcontainers.LowkeyVault.Tests/Testcontainers.LowkeyVault.Tests.csproj"/>
+        <Project Path="tests/Testcontainers.Mailpit.Tests/Testcontainers.Mailpit.Tests.csproj"/>
         <Project Path="tests/Testcontainers.MariaDb.Tests/Testcontainers.MariaDb.Tests.csproj"/>
         <Project Path="tests/Testcontainers.Milvus.Tests/Testcontainers.Milvus.Tests.csproj"/>
         <Project Path="tests/Testcontainers.Minio.Tests/Testcontainers.Minio.Tests.csproj"/>

docs/modules/index.md

@@ -52,6 +52,7 @@ await moduleNameContainer.StartAsync();
 | Kusto emulator    | `mcr.microsoft.com/azuredataexplorer/kustainer-linux:latest`        | [NuGet](https://www.nuget.org/packages/Testcontainers.Kusto)         | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Kusto)         |
 | LocalStack        | `localstack/localstack:2.0`                                         | [NuGet](https://www.nuget.org/packages/Testcontainers.LocalStack)    | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.LocalStack)    |
 | Lowkey Vault      | `nagyesta/lowkey-vault:2.7.1-ubi9-minimal`                          | [NuGet](https://www.nuget.org/packages/Testcontainers.LowkeyVault)   | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.LowkeyVault)   |
+| Mailpit           | `axllent/mailpit:v1.30`                                             | [NuGet](https://www.nuget.org/packages/Testcontainers.Mailpit)       | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Mailpit)       |
 | MariaDB           | `mariadb:10.10`                                                     | [NuGet](https://www.nuget.org/packages/Testcontainers.MariaDb)       | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.MariaDb)       |
 | Milvus            | `milvusdb/milvus:v2.3.10`                                           | [NuGet](https://www.nuget.org/packages/Testcontainers.Milvus)        | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Milvus)        |
 | MinIO             | `minio/minio:RELEASE.2023-01-31T02-24-19Z`                          | [NuGet](https://www.nuget.org/packages/Testcontainers.Minio)         | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Minio)         |

src/Testcontainers.Mailpit/.editorconfig

@@ -0,0 +1 @@
+root = true

src/Testcontainers.Mailpit/MailpitBuilder.cs

@@ -0,0 +1,143 @@
+namespace Testcontainers.Mailpit;
+
+/// <inheritdoc cref="ContainerBuilder{TBuilderEntity, TContainerEntity, TConfigurationEntity}" />
+[PublicAPI]
+public sealed class MailpitBuilder
+    : ContainerBuilder<MailpitBuilder, MailpitContainer, MailpitConfiguration>
+{
+    [Obsolete("This constant is obsolete and will be removed in the future. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
+    public const string MailpitImage = "axllent/mailpit:v1.30";
+
+    public const ushort SmtpPort = 1025;
+
+    public const ushort WebPort = 8025;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitBuilder" /> class.
+    /// </summary>
+    [Obsolete("This parameterless constructor is obsolete and will be removed. Use the constructor with the image parameter instead: https://github.com/testcontainers/testcontainers-dotnet/discussions/1470#discussioncomment-15185721.")]
+    public MailpitBuilder()
+        :this(MailpitImage)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitBuilder" /> class.
+    /// </summary>
+    /// <param name="image">The full Docker image name, including the image repository and tag (e.g., <c>axllent/mailpit:v1.30</c>).</param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/r/axllent/mailpit/tags" />.
+    /// </remarks>
+    public MailpitBuilder(string image)
+        : this(new DockerImage(image))
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitBuilder" /> class.
+    /// </summary>
+    /// <param name="image">An <see cref="IImage" /> instance that specifies the Docker image to be used for the container builder configuration.</param>
+    /// <remarks>
+    /// Docker image tags available at <see href="https://hub.docker.com/r/axllent/mailpit/tags" />.
+    /// </remarks>
+    public MailpitBuilder(IImage image)
+        : this(new MailpitConfiguration())
+    {
+        DockerResourceConfiguration = Init().WithImage(image).DockerResourceConfiguration;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitBuilder" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    private MailpitBuilder(MailpitConfiguration resourceConfiguration)
+        : base(resourceConfiguration)
+    {
+        DockerResourceConfiguration = resourceConfiguration;
+    }
+
+    /// <inheritdoc />
+    protected override MailpitConfiguration DockerResourceConfiguration { get; }
+
+    /// <summary>
+    /// Sets the Mailpit MP_SMTP_AUTH config.
+    /// </summary>
+    /// <param name="credentials">The credentials to be used in SMTP authentication.</param>
+    /// <param name="allowInsecure">
+    /// When <see langword="true"/>, the MP_SMTP_AUTH_ALLOW_INSECURE config is set to true to allow insecure PLAIN and LOGIN SMTP authentication.
+    /// When <see langword="false"/>, a self-signed certificate is used. Its subject and issuer are <c>CN=localhost, O=Mailpit self-signed certificate</c>.
+    /// </param>
+    /// <returns>A configured instance of <see cref="MailpitBuilder" />.</returns>
+    public MailpitBuilder WithSmtpAuthCredentials(NetworkCredential credentials, bool allowInsecure)
+    {
+        if (credentials == null)
+        {
+            throw new ArgumentNullException(nameof(credentials));
+        }
+
+        if (credentials.UserName.Contains(":"))
+        {
+            throw new ArgumentException("The UserName cannot contain a colon (:) character.", nameof(credentials));
+        }
+
+        // https://mailpit.axllent.org/docs/configuration/smtp/#adding-smtp-authentication
+        var builder = Merge(DockerResourceConfiguration, new MailpitConfiguration(smtpAuthCredentials: credentials, smtpAuthAllowInsecure: allowInsecure))
+            .WithEnvironment("MP_SMTP_AUTH", $"{credentials.UserName}:{credentials.Password}");
+
+        return allowInsecure
+            ? builder
+                .WithEnvironment("MP_SMTP_AUTH_ALLOW_INSECURE", "1")
+            : builder
+                 // https://mailpit.axllent.org/docs/configuration/certificates/#auto-generate-self-signed-certificates
+                .WithEnvironment("MP_SMTP_TLS_CERT", "sans:localhost")
+                .WithEnvironment("MP_SMTP_TLS_KEY", "sans:localhost");
+    }
+
+    /// <summary>
+    /// Sets the Mailpit MP_MAX_MESSAGES config.
+    /// Maximum number of messages to store. Mailpit will periodically delete the oldest messages if greater than this. Set to 0 to disable auto-deletion.
+    /// </summary>
+    /// <param name="maxMessages">The maximum number of messages to set.</param>
+    /// <returns>A configured instance of <see cref="MailpitBuilder" />.</returns>
+    public MailpitBuilder WithMaxMessages(uint maxMessages)
+    {
+        return Merge(DockerResourceConfiguration, new MailpitConfiguration(maxMessages: maxMessages))
+            .WithEnvironment("MP_MAX_MESSAGES", maxMessages.ToString());
+    }
+
+    /// <inheritdoc />
+    public override MailpitContainer Build()
+    {
+        Validate();
+        return new MailpitContainer(DockerResourceConfiguration);
+    }
+
+    /// <inheritdoc />
+    protected override MailpitBuilder Init()
+    {
+        return base.Init()
+            .WithPortBinding(SmtpPort, true)
+            .WithPortBinding(WebPort, true)
+            .WithWaitStrategy(Wait.ForUnixContainer().UntilHttpRequestIsSucceeded(request =>
+                // https://mailpit.axllent.org/docs/integration/healthcheck/
+                request.ForPort(WebPort).ForPath("/readyz")));
+    }
+
+    /// <inheritdoc />
+    protected override MailpitBuilder Clone(IResourceConfiguration<CreateContainerParameters> resourceConfiguration)
+    {
+        return Merge(DockerResourceConfiguration, new MailpitConfiguration(resourceConfiguration));
+    }
+
+    /// <inheritdoc />
+    protected override MailpitBuilder Clone(IContainerConfiguration resourceConfiguration)
+    {
+        return Merge(DockerResourceConfiguration, new MailpitConfiguration(resourceConfiguration));
+    }
+
+    /// <inheritdoc />
+    protected override MailpitBuilder Merge(MailpitConfiguration oldValue, MailpitConfiguration newValue)
+    {
+        return new MailpitBuilder(new MailpitConfiguration(oldValue, newValue));
+    }
+}

src/Testcontainers.Mailpit/MailpitConfiguration.cs

@@ -0,0 +1,77 @@
+namespace Testcontainers.Mailpit;
+
+/// <inheritdoc cref="ContainerConfiguration" />
+[PublicAPI]
+public sealed class MailpitConfiguration : ContainerConfiguration
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitConfiguration" /> class.
+    /// </summary>
+    /// <param name="smtpAuthCredentials">Username and password for SMTP authentication. The username must not contain a <c>:</c> character.</param>
+    /// <param name="smtpAuthAllowInsecure">Typically, STARTTLS is enforced for all SMTP authentication. This option allows insecure PLAIN & LOGIN SMTP authentication.</param>
+    /// <param name="maxMessages">Maximum number of messages to store. Mailpit will periodically delete the oldest messages if greater than this. Set to 0 to disable auto-deletion.</param>
+    public MailpitConfiguration(NetworkCredential smtpAuthCredentials = null, bool smtpAuthAllowInsecure = true, uint maxMessages = 100)
+    {
+        SmtpAuthCredentials = smtpAuthCredentials;
+        SmtpAuthAllowInsecure = smtpAuthAllowInsecure;
+        MaxMessages = maxMessages;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitConfiguration" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    public MailpitConfiguration(IResourceConfiguration<CreateContainerParameters> resourceConfiguration)
+        : base(resourceConfiguration)
+    {
+        // Passes the configuration upwards to the base implementations to create an updated immutable copy.
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitConfiguration" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    public MailpitConfiguration(IContainerConfiguration resourceConfiguration)
+        : base(resourceConfiguration)
+    {
+        // Passes the configuration upwards to the base implementations to create an updated immutable copy.
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitConfiguration" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    public MailpitConfiguration(MailpitConfiguration resourceConfiguration)
+        : this(new MailpitConfiguration(), resourceConfiguration)
+    {
+        // Passes the configuration upwards to the base implementations to create an updated immutable copy.
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitConfiguration" /> class.
+    /// </summary>
+    /// <param name="oldValue">The old Docker resource configuration.</param>
+    /// <param name="newValue">The new Docker resource configuration.</param>
+    public MailpitConfiguration(MailpitConfiguration oldValue, MailpitConfiguration newValue)
+        : base(oldValue, newValue)
+    {
+        SmtpAuthCredentials = BuildConfiguration.Combine(oldValue.SmtpAuthCredentials, newValue.SmtpAuthCredentials);
+        SmtpAuthAllowInsecure = BuildConfiguration.Combine(oldValue.SmtpAuthAllowInsecure, newValue.SmtpAuthAllowInsecure);
+        MaxMessages = BuildConfiguration.Combine(oldValue.MaxMessages, newValue.MaxMessages);
+    }
+
+    /// <summary>
+    /// Username and password for SMTP authentication. The username must not contain a <c>:</c> character.
+    /// </summary>
+    public NetworkCredential SmtpAuthCredentials { get; }
+
+    /// <summary>
+    /// Typically, STARTTLS is enforced for all SMTP authentication. This option allows insecure PLAIN & LOGIN SMTP authentication.
+    /// </summary>
+    public bool SmtpAuthAllowInsecure { get; }
+
+    /// <summary>
+    /// Maximum number of messages to store. Mailpit will periodically delete the oldest messages if greater than this. Set to 0 to disable auto-deletion.
+    /// </summary>
+    public uint MaxMessages { get; }
+}

src/Testcontainers.Mailpit/MailpitContainer.cs

@@ -0,0 +1,28 @@
+namespace Testcontainers.Mailpit;
+
+/// <inheritdoc cref="DockerContainer" />
+[PublicAPI]
+public sealed class MailpitContainer : DockerContainer
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitContainer" /> class.
+    /// </summary>
+    /// <param name="configuration">The container configuration.</param>
+    public MailpitContainer(MailpitConfiguration configuration)
+        : base(configuration)
+    {
+    }
+
+    /// <summary>
+    /// The SMTP server port.
+    /// </summary>
+    public ushort SmtpPort => GetMappedPublicPort(MailpitBuilder.SmtpPort);
+
+    /// <summary>
+    /// Gets the web server address of the user interface. Can also be used as the base URL for the <see href="https://mailpit.axllent.org/docs/api-v1/"> REST API</see>.
+    /// </summary>
+    public string GetWebAddress()
+    {
+        return new UriBuilder(Uri.UriSchemeHttp, Hostname, GetMappedPublicPort(MailpitBuilder.WebPort)).ToString();
+    }
+}

src/Testcontainers.Mailpit/Testcontainers.Mailpit.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+    <PropertyGroup>
+        <TargetFrameworks>net8.0;net9.0;net10.0;netstandard2.0;netstandard2.1</TargetFrameworks>
+        <LangVersion>latest</LangVersion>
+    </PropertyGroup>
+    <ItemGroup>
+        <PackageReference Include="JetBrains.Annotations" VersionOverride="2023.3.0" PrivateAssets="All"/>
+    </ItemGroup>
+    <ItemGroup>
+        <ProjectReference Include="../Testcontainers/Testcontainers.csproj"/>
+    </ItemGroup>
+</Project>

src/Testcontainers.Mailpit/Usings.cs

@@ -0,0 +1,8 @@
+global using System;
+global using System.Net;
+global using Docker.DotNet.Models;
+global using DotNet.Testcontainers.Builders;
+global using DotNet.Testcontainers.Configurations;
+global using DotNet.Testcontainers.Containers;
+global using DotNet.Testcontainers.Images;
+global using JetBrains.Annotations;

tests/Testcontainers.Mailpit.Tests/.editorconfig

@@ -0,0 +1 @@
+root = true

tests/Testcontainers.Mailpit.Tests/.runs-on

@@ -0,0 +1 @@
+ubuntu-24.04

tests/Testcontainers.Mailpit.Tests/Dockerfile

@@ -0,0 +1 @@
+FROM axllent/mailpit:v1.30@sha256:5a49a77c5bdbe7c5474450b4f46348d09949df3695257729c93a30369382d4f6