Implemented a MailgunClient.

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Implemented a MailgunClient.
+
 ### Fixed
 
 - Password recovery message template.

Logitar.NET.sln

@@ -47,15 +47,21 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Logitar.Net.UnitTests", "te
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Demo", "Demo", "{202D8AE0-51C3-44C0-951D-CDF464D1FCFB}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Logitar.Demo", "demo\Logitar.Demo\Logitar.Demo.csproj", "{810DEC30-7D48-4B81-9668-AF78F21E7D53}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Logitar.Demo", "demo\Logitar.Demo\Logitar.Demo.csproj", "{810DEC30-7D48-4B81-9668-AF78F21E7D53}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Logitar.Net.IntegrationTests", "tests\Logitar.Net.IntegrationTests\Logitar.Net.IntegrationTests.csproj", "{6F03DBDD-196D-463B-A1F8-DB6081981FBE}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Logitar.Net.IntegrationTests", "tests\Logitar.Net.IntegrationTests\Logitar.Net.IntegrationTests.csproj", "{6F03DBDD-196D-463B-A1F8-DB6081981FBE}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Logitar.Net.Mail.SendGrid", "src\Logitar.Net.Mail.SendGrid\Logitar.Net.Mail.SendGrid.csproj", "{ECEF5AB1-2AB1-4564-84F6-BEB0729E7B8C}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Logitar.Net.Mail.SendGrid", "src\Logitar.Net.Mail.SendGrid\Logitar.Net.Mail.SendGrid.csproj", "{ECEF5AB1-2AB1-4564-84F6-BEB0729E7B8C}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Logitar.Net.Mail.SendGrid.UnitTests", "tests\Logitar.Net.Mail.SendGrid.UnitTests\Logitar.Net.Mail.SendGrid.UnitTests.csproj", "{8C98F0D3-E27B-4B0F-AB0F-DEE5AF3BAA48}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Logitar.Net.Mail.SendGrid.UnitTests", "tests\Logitar.Net.Mail.SendGrid.UnitTests\Logitar.Net.Mail.SendGrid.UnitTests.csproj", "{8C98F0D3-E27B-4B0F-AB0F-DEE5AF3BAA48}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Logitar.Net.Mail.SendGrid.IntegrationTests", "tests\Logitar.Net.Mail.SendGrid.IntegrationTests\Logitar.Net.Mail.SendGrid.IntegrationTests.csproj", "{8710CBF6-653F-4D52-929C-468A472EADEF}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Logitar.Net.Mail.SendGrid.IntegrationTests", "tests\Logitar.Net.Mail.SendGrid.IntegrationTests\Logitar.Net.Mail.SendGrid.IntegrationTests.csproj", "{8710CBF6-653F-4D52-929C-468A472EADEF}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Logitar.Net.Mail.Mailgun", "src\Logitar.Net.Mail.Mailgun\Logitar.Net.Mail.Mailgun.csproj", "{D2B2B2D0-577E-422D-A3DF-68E38ABB382A}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Logitar.Net.Mail.Mailgun.UnitTests", "tests\Logitar.Net.Mail.Mailgun.UnitTests\Logitar.Net.Mail.Mailgun.UnitTests.csproj", "{5AB2A6A7-9CCA-4ADA-B4AE-81C668D1D412}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Logitar.Net.Mail.Mailgun.IntegrationTests", "tests\Logitar.Net.Mail.Mailgun.IntegrationTests\Logitar.Net.Mail.Mailgun.IntegrationTests.csproj", "{C9D19807-4BB8-4C5F-9744-9B381FE21DC7}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -139,6 +145,18 @@ Global
 		{8710CBF6-653F-4D52-929C-468A472EADEF}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{8710CBF6-653F-4D52-929C-468A472EADEF}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{8710CBF6-653F-4D52-929C-468A472EADEF}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D2B2B2D0-577E-422D-A3DF-68E38ABB382A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D2B2B2D0-577E-422D-A3DF-68E38ABB382A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D2B2B2D0-577E-422D-A3DF-68E38ABB382A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D2B2B2D0-577E-422D-A3DF-68E38ABB382A}.Release|Any CPU.Build.0 = Release|Any CPU
+		{5AB2A6A7-9CCA-4ADA-B4AE-81C668D1D412}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{5AB2A6A7-9CCA-4ADA-B4AE-81C668D1D412}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{5AB2A6A7-9CCA-4ADA-B4AE-81C668D1D412}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{5AB2A6A7-9CCA-4ADA-B4AE-81C668D1D412}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C9D19807-4BB8-4C5F-9744-9B381FE21DC7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C9D19807-4BB8-4C5F-9744-9B381FE21DC7}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C9D19807-4BB8-4C5F-9744-9B381FE21DC7}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C9D19807-4BB8-4C5F-9744-9B381FE21DC7}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -156,6 +174,8 @@ Global
 		{6F03DBDD-196D-463B-A1F8-DB6081981FBE} = {746BA5D1-0E1A-4191-9645-88D14B1C69BF}
 		{8C98F0D3-E27B-4B0F-AB0F-DEE5AF3BAA48} = {746BA5D1-0E1A-4191-9645-88D14B1C69BF}
 		{8710CBF6-653F-4D52-929C-468A472EADEF} = {746BA5D1-0E1A-4191-9645-88D14B1C69BF}
+		{5AB2A6A7-9CCA-4ADA-B4AE-81C668D1D412} = {746BA5D1-0E1A-4191-9645-88D14B1C69BF}
+		{C9D19807-4BB8-4C5F-9744-9B381FE21DC7} = {746BA5D1-0E1A-4191-9645-88D14B1C69BF}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {B0AA9E53-02AD-4000-8ED5-53AFF5D1B32D}

src/Logitar.Net.Mail.Mailgun/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Logitar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/Logitar.Net.Mail.Mailgun/Logitar.Net.Mail.Mailgun.csproj

@@ -0,0 +1,53 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <WarningsAsErrors>Nullable</WarningsAsErrors>
+    <GeneratePackageOnBuild>True</GeneratePackageOnBuild>
+    <Title>Logitar.Net.Mail.Mailgun</Title>
+    <Authors>Francis Pion</Authors>
+    <Product>Logitar.NET</Product>
+    <Description>Enhances the System.Net.Mail namespace, using the Mailgun API for email management.</Description>
+    <Copyright>© 2024 Logitar All Rights Reserved.</Copyright>
+    <PackageIcon>logitar.png</PackageIcon>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <RepositoryType>git</RepositoryType>
+    <RepositoryUrl>https://github.com/Logitar/Logitar.NET</RepositoryUrl>
+    <AssemblyVersion>6.0.0.0</AssemblyVersion>
+    <FileVersion>$(AssemblyVersion)</FileVersion>
+    <PackageLicenseFile>LICENSE</PackageLicenseFile>
+    <PackageRequireLicenseAcceptance>True</PackageRequireLicenseAcceptance>
+    <Version>6.0.0</Version>
+    <NeutralLanguage>en-CA</NeutralLanguage>
+    <GenerateDocumentationFile>True</GenerateDocumentationFile>
+    <PackageReleaseNotes>Implemented a MailgunClient.</PackageReleaseNotes>
+    <PackageTags>logitar net framework http email mailgun</PackageTags>
+    <PackageProjectUrl>https://github.com/Logitar/Logitar.NET/tree/dev/src/Logitar.Net.Mail.Mailgun</PackageProjectUrl>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Update="LICENSE">
+      <PackagePath>\</PackagePath>
+      <Pack>True</Pack>
+    </None>
+    <None Update="logitar.png">
+      <PackagePath>\</PackagePath>
+      <Pack>True</Pack>
+    </None>
+    <None Update="README.md">
+      <PackagePath>\</PackagePath>
+      <Pack>True</Pack>
+    </None>
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Logitar.Net\Logitar.Net.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="System.Net.Mail" />
+  </ItemGroup>
+
+</Project>

src/Logitar.Net.Mail.Mailgun/MailgunClient.cs

@@ -0,0 +1,130 @@
+using Logitar.Net.Http;
+using Logitar.Net.Mail.Mailgun.Settings;
+
+namespace Logitar.Net.Mail.Mailgun;
+
+/// <summary>
+/// Implements methods to manage email messages with Mailgun.
+/// </summary>
+public class MailgunClient : IDisposable, IMailClient
+{
+  /// <summary>
+  /// Gets or sets the JSON API client used to send HTTP requests to the Mailgun API.
+  /// </summary>
+  protected virtual JsonApiClient Client { get; set; }
+  /// <summary>
+  /// Gets or sets a value indicating whether or not to dispose the API client when disposing this instance.
+  /// </summary>
+  protected virtual bool DisposeClient { get; set; }
+  /// <summary>
+  /// Gets or sets the settings of the Mailgun API.
+  /// </summary>
+  protected virtual IMailgunSettings Settings { get; set; }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="MailgunClient"/> class.
+  /// </summary>
+  public MailgunClient() : this(new MailgunSettings())
+  {
+  }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="MailgunClient"/> class.
+  /// </summary>
+  /// <param name="apiKey">The API key used to authorize the Mailgun API calls.</param>
+  /// <param name="domainName">The name of the domain used to send messages from.</param>
+  public MailgunClient(string apiKey, string domainName) : this(new MailgunSettings(apiKey, domainName))
+  {
+  }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="MailgunClient"/> class.
+  /// </summary>
+  /// <param name="settings">The Mailgun API settings.</param>
+  public MailgunClient(IMailgunSettings settings) : this(new HttpClient(), settings)
+  {
+    DisposeClient = true;
+  }
+
+  /// <summary>
+  /// Initializes a new instance of the <see cref="MailgunClient"/> class.
+  /// </summary>
+  /// <param name="client">An HTTP client intance.</param>
+  /// <param name="settings">The Mailgun API settings.</param>
+  public MailgunClient(HttpClient client, IMailgunSettings settings)
+  {
+    Client = new JsonApiClient(client, settings.ToHttpApiSettings());
+    Settings = settings;
+  }
+
+  /// <summary>
+  /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
+  /// </summary>
+  public virtual void Dispose()
+  {
+    if (DisposeClient)
+    {
+      Client.Dispose();
+    }
+
+    GC.SuppressFinalize(this);
+  }
+
+  /// <summary>
+  /// Sends the specified email message.
+  /// </summary>
+  /// <param name="message">The message to send.</param>
+  /// <param name="cancellationToken">The cancellation token.</param>
+  /// <returns>The operation result.</returns>
+  public virtual async Task<SendMailResult> SendAsync(MailMessage message, CancellationToken cancellationToken)
+  {
+    MailAddress from = message.Sender ?? message.From
+      ?? throw new ArgumentException($"At least one of the following must be provided: {nameof(message.From)}, {nameof(message.Sender)}.", nameof(message));
+
+    MultipartFormDataContent content = new()
+    {
+      { new StringContent(from.ToString()), "from" },
+      { new StringContent(message.Subject), "subject" },
+      { new StringContent(message.Body), message.IsBodyHtml ? "html" : "text" },
+    };
+
+    foreach (MailAddress recipient in message.To)
+    {
+      content.Add(new StringContent(recipient.ToString()), "to");
+    }
+    foreach (MailAddress recipient in message.CC)
+    {
+      content.Add(new StringContent(recipient.ToString()), "cc");
+    }
+    foreach (MailAddress recipient in message.Bcc)
+    {
+      content.Add(new StringContent(recipient.ToString()), "bcc");
+    }
+
+    EndPointSettings endPoint = Settings.SendMail;
+    Uri requestUri = new(endPoint.Path.Replace("{DomainName}", Settings.DomainName), UriKind.RelativeOrAbsolute);
+    HttpRequestParameters parameters = new(endPoint.HttpMethod, requestUri)
+    {
+      Content = content,
+      ThrowOnFailure = false
+    };
+
+    JsonApiResult result = await Client.SendAsync(parameters, cancellationToken);
+    return new SendMailResult(result.Status.IsSuccess, GetData(result));
+  }
+
+  /// <summary>
+  /// Builds a data dictionary from the specified API result.
+  /// </summary>
+  /// <param name="result">The API result.</param>
+  /// <returns>The data dictionary.</returns>
+  protected virtual IDictionary<string, object?> GetData(JsonApiResult result) => new Dictionary<string, object?>
+  {
+    [nameof(result.Version)] = result.Version,
+    [nameof(result.Status)] = result.Status,
+    [nameof(result.ReasonPhrase)] = result.ReasonPhrase,
+    [nameof(result.Headers)] = result.Headers,
+    [nameof(result.TrailingHeaders)] = result.TrailingHeaders,
+    [nameof(result.JsonContent)] = result.JsonContent
+  };
+}

src/Logitar.Net.Mail.Mailgun/README.md

@@ -0,0 +1,3 @@
+# Logitar.Net.Mail.Mailgun
+
+Enhances the System.Net.Mail namespace, using the Mailgun API for email management.

src/Logitar.Net.Mail.Mailgun/Settings/EndPointSettings.cs

@@ -0,0 +1,25 @@
+namespace Logitar.Net.Mail.Mailgun.Settings;
+
+/// <summary>
+/// Implements the settings of a Mailgun API endpoint.
+/// </summary>
+public record EndPointSettings : IEndPointSettings
+{
+  /// <summary>
+  /// Gets or sets string representation of the endpoint's HTTP method.
+  /// </summary>
+  public string Method { get; set; } = HttpMethod.Get.Method;
+  /// <summary>
+  /// Gets the HTTP method of the endpoint.
+  /// </summary>
+  public HttpMethod HttpMethod => new(Method);
+
+  /// <summary>
+  /// Gets or sets a string representation of the endpoint's path.
+  /// </summary>
+  public string Path { get; set; } = string.Empty;
+  /// <summary>
+  /// Gets the path of the endpoint.
+  /// </summary>
+  public Uri UriPath => new(Path, UriKind.RelativeOrAbsolute);
+}

src/Logitar.Net.Mail.Mailgun/Settings/IEndPointSettings.cs

@@ -0,0 +1,25 @@
+namespace Logitar.Net.Mail.Mailgun.Settings;
+
+/// <summary>
+/// Defines the settings of a Mailgun API endpoint.
+/// </summary>
+public interface IEndPointSettings
+{
+  /// <summary>
+  /// Gets string representation of the endpoint's HTTP method.
+  /// </summary>
+  string Method { get; }
+  /// <summary>
+  /// Gets the HTTP method of the endpoint.
+  /// </summary>
+  HttpMethod HttpMethod { get; }
+
+  /// <summary>
+  /// Gets a string representation of the endpoint's path.
+  /// </summary>
+  string Path { get; }
+  /// <summary>
+  /// Gets the path of the endpoint.
+  /// </summary>
+  Uri UriPath { get; }
+}

src/Logitar.Net.Mail.Mailgun/Settings/IMailgunSettings.cs

@@ -0,0 +1,39 @@
+namespace Logitar.Net.Mail.Mailgun.Settings;
+
+/// <summary>
+/// Defines the settings of the Mailgun API.
+/// </summary>
+public interface IMailgunSettings
+{
+  /// <summary>
+  /// Gets the username used to authorize the Mailgun API calls.
+  /// </summary>
+  string Username { get; }
+  /// <summary>
+  /// Gets the password used to authorize the Mailgun API calls, typically your API key.
+  /// </summary>
+  string? Password { get; }
+  /// <summary>
+  /// Gets the API key used to authorize the Mailgun API calls.
+  /// </summary>
+  string? ApiKey { get; }
+
+  /// <summary>
+  /// Gets the base Uniform Resource Locator (URL) of the Mailgun API.
+  /// </summary>
+  string BaseUrl { get; }
+  /// <summary>
+  /// Gets the base Uniform Resource Identifier (URI) of the Mailgun API.
+  /// </summary>
+  Uri BaseUri { get; }
+
+  /// <summary>
+  /// Gets the name of the domain to send messages from.
+  /// </summary>
+  string? DomainName { get; }
+
+  /// <summary>
+  /// Gets the send mail end point information.
+  /// </summary>
+  EndPointSettings SendMail { get; }
+}