feat: 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,167 @@
+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 <c>MP_SMTP_AUTH</c> configuration.
+    /// </summary>
+    /// <param name="credentials">The credentials to use for SMTP authentication.</param>
+    /// <param name="allowInsecure">
+    /// When <see langword="true" />, sets the Mailpit <c>MP_SMTP_AUTH_ALLOW_INSECURE</c>
+    /// configuration to allow insecure PLAIN and LOGIN SMTP authentication.
+    /// When <see langword="false" />, configures Mailpit to use a self-signed
+    /// certificate by setting <c>MP_SMTP_TLS_CERT</c> and <c>MP_SMTP_TLS_KEY</c>
+    /// to <c>sans:localhost</c>. The certificate subject and issuer are
+    /// <c>CN=localhost, O=Mailpit self-signed certificate</c>.
+    /// </param>
+    /// <remarks>
+    /// See <see href="https://mailpit.axllent.org/docs/configuration/certificates/#auto-generate-self-signed-certificates" />.
+    /// </remarks>
+    /// <returns>A configured <see cref="MailpitBuilder" /> instance.</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));
+        }
+
+        // TODO:
+        // This prepares a full environment replacement once dictionary composition
+        // supports ComposableDictionary for environments. Until that, stale keys
+        // are still preserved by the current IReadOnlyDictionary merge behavior.
+        var environments = DockerResourceConfiguration.Environments.ToDictionary(item => item.Key, item => item.Value);
+        environments.Remove("MP_SMTP_AUTH_ALLOW_INSECURE");
+        environments.Remove("MP_SMTP_TLS_CERT");
+        environments.Remove("MP_SMTP_TLS_KEY");
+
+        // https://mailpit.axllent.org/docs/configuration/smtp/#adding-smtp-authentication.
+        environments["MP_SMTP_AUTH"] = $"{credentials.UserName}:{credentials.Password}";
+
+        if (allowInsecure)
+        {
+            environments["MP_SMTP_AUTH_ALLOW_INSECURE"] = "1";
+        }
+        else
+        {
+            environments["MP_SMTP_TLS_CERT"] = "sans:localhost";
+            environments["MP_SMTP_TLS_KEY"] = "sans:localhost";
+        }
+
+        return WithEnvironment(new OverwriteDictionary<string, string>(environments));
+    }
+
+    /// <summary>
+    /// Sets the Mailpit <c>MP_MAX_MESSAGES</c> configuration.
+    /// Specifies the maximum number of messages to store. Mailpit periodically
+    /// deletes the oldest messages when this limit is exceeded.
+    /// Set to <c>0</c> to disable automatic deletion.
+    /// </summary>
+    /// <param name="maxMessages">The maximum number of messages to store.</param>
+    /// <returns>A configured <see cref="MailpitBuilder" /> instance.</returns>
+    public MailpitBuilder WithMaxMessages(uint maxMessages)
+    {
+        return 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 =>
+                request.ForPath("/readyz").ForPort(WebPort)));
+    }
+
+    /// <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,53 @@
+namespace Testcontainers.Mailpit;
+
+/// <inheritdoc cref="ContainerConfiguration" />
+[PublicAPI]
+public sealed class MailpitConfiguration : ContainerConfiguration
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MailpitConfiguration" /> class.
+    /// </summary>
+    public MailpitConfiguration()
+    {
+    }
+
+    /// <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)
+    {
+    }
+}

src/Testcontainers.Mailpit/MailpitContainer.cs

@@ -0,0 +1,32 @@
+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>
+    /// Gets the SMTP port.
+    /// </summary>
+    public ushort SmtpPort => GetMappedPublicPort(MailpitBuilder.SmtpPort);
+
+    /// <summary>
+    /// Gets the Mailpit web server address.
+    /// </summary>
+    /// <remarks>
+    /// This address can also be used as the base URL for the <see href="https://mailpit.axllent.org/docs/api-v1/">REST API</see>.
+    /// </remarks>
+    /// <returns>The Mailpit web server address.</returns>
+    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,9 @@
+global using System;
+global using System.Linq;
+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