Feat/mailgun entry point

src/Sinch/Core/UrlResolver.cs

@@ -1,5 +1,6 @@
 using System;
 using Sinch.Conversation;
+using Sinch.Mailgun;
 using Sinch.SMS;
 using Sinch.Voice;
 
@@ -83,5 +84,25 @@ public Uri ResolveSmsServicePlanIdUrl(SmsServicePlanIdRegion smsServicePlanIdReg
             return new Uri(string.Format(smsApiServicePlanIdUrlTemplate,
                 smsServicePlanIdRegion.Value.ToLowerInvariant()));
         }
+
+        public Uri ResolveMailgunUrl(MailgunRegion mailgunRegion)
+        {
+            if (!string.IsNullOrEmpty(_apiUrlOverrides?.MailgunUrl)) return new Uri(_apiUrlOverrides.MailgunUrl);
+
+            string? mailgunUrl;
+            switch (mailgunRegion)
+            {
+                case MailgunRegion.Us:
+                    mailgunUrl = "https://api.mailgun.net";
+                    break;
+                case MailgunRegion.Eu:
+                    mailgunUrl = "https://api.eu.mailgun.net";
+                    break;
+                default:
+                    throw new ArgumentOutOfRangeException(nameof(mailgunRegion), mailgunRegion, "Unreachable");
+            }
+
+            return new Uri(mailgunUrl);
+        }
     }
 }

src/Sinch/Mailgun/MailgunRegion.cs

@@ -0,0 +1,18 @@
+namespace Sinch.Mailgun
+{
+    /// <summary>
+    ///     Mailgun allows the ability to send and receive email in both US and EU regions.
+    ///     Be sure to use the appropriate region on which you have created your domain.
+    /// </summary>
+    public enum MailgunRegion
+    {
+        /// <summary>
+        ///     United States region
+        /// </summary>
+        Us,
+        /// <summary>
+        ///     Europe region
+        /// </summary>
+        Eu
+    }
+}

src/Sinch/Mailgun/SinchMailgunClient.cs

@@ -0,0 +1,23 @@
+using System;
+using Sinch.Core;
+using Sinch.Logger;
+
+namespace Sinch.Mailgun
+{
+    /// <summary>
+    ///     The Mailgun API is part of the Sinch family and enables you to send, track, and receive email effortlessly. 
+    /// </summary>
+    public interface ISinchMailgunClient
+    {
+        // TBD: add domains
+    }
+
+    /// <inheritdoc />
+    internal class SinchMailgunClient : ISinchMailgunClient
+    {
+        public SinchMailgunClient(Uri baseUrl, Http http, LoggerFactory? loggerFactory = null)
+        {
+            // TBD: implement domains 
+        }
+    }
+}

src/Sinch/SinchClient.cs

@@ -7,6 +7,7 @@
 using Sinch.Conversation;
 using Sinch.Core;
 using Sinch.Logger;
+using Sinch.Mailgun;
 using Sinch.Numbers;
 using Sinch.SMS;
 using Sinch.Verification;
@@ -111,6 +112,17 @@ public ISinchVerificationClient Verification(string appKey, string appSecret,
         /// <param name="voiceRegion">See <see cref="VoiceRegion" />. Defaults to <see cref="VoiceRegion.Global" /></param>
         /// <returns></returns>
         public ISinchVoiceClient Voice(string appKey, string appSecret, VoiceRegion? voiceRegion = null);
+
+        /// <summary>
+        ///     APIs are at the heart of Mailgun.
+        ///     Our goal is to provide developers worldwide with an accessible and straightforward way to send,
+        ///     receive, and track emails effortlessly.
+        /// </summary>
+        /// <param name="apiKey">When you sign up for Mailgun, a primary account API key is generated.
+        /// This key allows you to perform all CRUD operations via our various API endpoints and for any of your sending domains. </param>
+        /// <param name="region"><see cref="MailgunRegion"/></param>
+        /// <returns></returns>
+        public ISinchMailgunClient Mailgun(string apiKey, MailgunRegion region);
     }
 
     public class SinchClient : ISinchClient
@@ -274,6 +286,21 @@ public ISinchVoiceClient Voice(string appKey, string appSecret,
                 _urlResolver.ResolveVoiceApplicationManagementUrl());
         }
 
+        /// <inheritdoc />
+        public ISinchMailgunClient Mailgun(string apiKey, MailgunRegion region)
+        {
+            if (string.IsNullOrEmpty(apiKey))
+            {
+                throw new ArgumentNullException(nameof(apiKey), "apiKey shouldn't be null or empty");
+            }
+            var baseUrl = _urlResolver.ResolveMailgunUrl(region);
+            var mailgunAuth = new BasicAuth(appKey: "api", appSecret: apiKey);
+            // NOTE: jsonNamingPolicy will not play a role here as property naming of mailgun is inconsistent
+            // meaning, all lifting will be done through JsonPropertyNamingAttribute
+            var http = new Http(mailgunAuth, _httpClient, _loggerFactory?.Create<IHttp>(), JsonNamingPolicy.CamelCase);
+            return new SinchMailgunClient(baseUrl, http, _loggerFactory);
+        }
+
         private void ValidateCommonCredentials()
         {
             var exceptions = new List<Exception>();

src/Sinch/SinchOptions.cs

@@ -137,5 +137,10 @@ public sealed class ApiUrlOverrides
         ///     Overrides Numbers api base url
         /// </summary>
         public string? NumbersUrl { get; init; }
+
+        /// <summary>
+        ///     Overrides Mailgun api base url
+        /// </summary>
+        public string? MailgunUrl { get; init; }
     }
 }

tests/Sinch.Tests/Core/UrlResolverTests.cs

@@ -3,6 +3,7 @@
 using FluentAssertions;
 using Sinch.Conversation;
 using Sinch.Core;
+using Sinch.Mailgun;
 using Sinch.SMS;
 using Sinch.Voice;
 using Xunit;
@@ -314,5 +315,60 @@ public void ResolveSmsServicePlanIdUrl(SmsServicePlanIdRegion smsServicePlanIdRe
                 : new Uri(apiUrlOverrides.SmsUrl);
             smsUrl.Should().BeEquivalentTo(expectedUrl);
         }
+
+
+        public static IEnumerable<object[]> MailgunUrlData => new List<object[]>
+        {
+            new object[]
+            {
+                MailgunRegion.Us,
+                null,
+            },
+            new object[]
+            {
+                MailgunRegion.Eu,
+                null,
+            },
+            new object[]
+            {
+                MailgunRegion.Eu,
+                new ApiUrlOverrides()
+                {
+                    MailgunUrl = null
+                }
+            },
+            new object[]
+            {
+                MailgunRegion.Eu,
+                new ApiUrlOverrides()
+                {
+                    MailgunUrl = "https://my-mailgun-proxy.net"
+                }
+            },
+        };
+
+        [Theory]
+        [MemberData(nameof(MailgunUrlData))]
+        public void ResolveMailgunUrl(MailgunRegion region, ApiUrlOverrides apiUrlOverrides)
+        {
+            var actual = new UrlResolver(apiUrlOverrides).ResolveMailgunUrl(region);
+
+            if (apiUrlOverrides is { MailgunUrl: not null })
+            {
+                actual.Should().BeEquivalentTo(new Uri(apiUrlOverrides.MailgunUrl));
+            }
+            else
+            {
+                if (region == MailgunRegion.Eu)
+                {
+                    actual.Should().BeEquivalentTo(new Uri("https://api.eu.mailgun.net"));
+                }
+                else
+                {
+                    actual.Should().BeEquivalentTo(new Uri("https://api.mailgun.net"));
+                }
+            }
+
+        }
     }
 }

tests/Sinch.Tests/Mailgun/MailgunClientTests.cs

@@ -0,0 +1,28 @@
+using System;
+using FluentAssertions;
+using Sinch.Mailgun;
+using Xunit;
+
+namespace Sinch.Tests.Mailgun
+{
+    public class MailgunClientTests
+    {
+        [Fact]
+        public void InitMailgunClient()
+        {
+            var mailgun = new SinchClient(default, default, default).Mailgun("apikey", MailgunRegion.Eu);
+
+            mailgun.Should().NotBeNull();
+        }
+
+        [Theory]
+        [InlineData("")]
+        [InlineData(null)]
+        public void FailEmptyApiKey(string apiKey)
+        {
+            var mailgunCreation = () => new SinchClient(default, default, default).Mailgun(apiKey, MailgunRegion.Eu);
+
+            mailgunCreation.Should().Throw<ArgumentNullException>();
+        }
+    }
+}