Changed from MimeMessageSender to SmtpSender.

Author: danzuep

.github/workflows/_pipeline.yml

@@ -44,27 +44,27 @@ jobs:
 
   deploy_core:
     # if: ${{ inputs.environment == 'release' }}
-    needs: build_core
+    needs: [version,build_core]
     uses: ./.github/workflows/_deploy-nuget.yml
     with:
-    environment: ${{ inputs.environment }}
-    project-name: 'MailKitSimplified.Core'
-    version: ${{ needs.version.outputs.version }}
+      environment: ${{ inputs.environment }}
+      project-name: 'MailKitSimplified.Core'
+      version: ${{ needs.version.outputs.version }}
     secrets: inherit
 
   deploy_sender:
     # if: ${{ inputs.environment == 'release' }}
-    needs: build_sender
+    needs: [version,build_sender]
     uses: ./.github/workflows/_deploy-nuget.yml
     with:
-    environment: ${{ inputs.environment }}
-    project-name: 'MailKitSimplified.Sender'
-    version: ${{ needs.version.outputs.version }}
+      environment: ${{ inputs.environment }}
+      project-name: 'MailKitSimplified.Sender'
+      version: ${{ needs.version.outputs.version }}
     secrets: inherit
 
   # deploy_receiver:
   #   if: ${{ inputs.environment == 'release' }} && {{ github.event_name != 'pull_request' }}
-  #   needs: build_receiver
+  #   needs: [version,build_receiver]
   #   uses: ./.github/workflows/_deploy-nuget.yml
   #   with:
   #     environment: ${{ inputs.environment }}

README.md

@@ -1,19 +1,27 @@
 # MailKitSimplified [![Build and Test results summary](https://github.com/danzuep/MailKitSimplified/actions/workflows/development.yml/badge.svg)](https://github.com/danzuep/MailKitSimplified/actions/workflows/development.yml)
 
-Sending and receiving emails sounds simple, after all, electronic mail existed [decades](https://en.wikipedia.org/wiki/History_of_email) before the [Internet](https://en.wikipedia.org/wiki/History_of_the_Internet). If you're looking for a an all-in-one .NET solution for email, you'll quickly discover [MailKit](https://github.com/jstedfast/MailKit) is recommended by even the likes of [Microsoft](https://learn.microsoft.com/en-us/dotnet/api/system.net.mail.smtpclient?view=net-6.0#remarks). Unfortunately for new users though, MailKit can do too much, so when I first started using it I was surprised at how many configuration steps were involved in getting it set up, and on the receiving end how poorly some real-world SMTP servers out there implement [the standard](https://www.rfc-editor.org/rfc/rfc2822). The aim of this package is to make sending an email as simple as possible.
+Sending and receiving emails sounds simple, after all, electronic mail existed [decades](https://en.wikipedia.org/wiki/History_of_email) before the [Internet](https://en.wikipedia.org/wiki/History_of_the_Internet). If you're looking for a an all-in-one .NET solution for email, you'll quickly discover [MailKit](https://github.com/jstedfast/MailKit) is recommended by even the likes of [Microsoft](https://learn.microsoft.com/en-us/dotnet/api/system.net.mail.smtpclient?view=net-6.0#remarks) due to how it implements the [RFC standard](https://www.rfc-editor.org/rfc/rfc2822). Unfortunately the downside of doing it all is that MailKit can be difficult to [set up](https://github.com/jstedfast/MailKit#using-mailkit) [and use](https://github.com/jstedfast/MimeKit/blob/master/FAQ.md#messages-1), especially the first time you go to try something like [checking attachments](https://github.com/jstedfast/MimeKit/blob/master/FAQ.md#q-how-do-i-tell-if-a-message-has-attachments) or [writing a reply](https://github.com/jstedfast/MimeKit/blob/master/FAQ.md#q-how-do-i-reply-to-a-message). The aim of this package is to make sending (and receiving) emails as simple as possible!
 
-## Sender Usage
+Sending an email is now as easy as:
+```csharp
+await writeEmail.To("test@localhost").SendAsync();
+```
+
+## MailKitSimplified.Sender Usage
 
 ### Setup
 
-If you're not familiar with dependency injection then just use this:
-```
-using var smtpSender = MimeMessageSender.Create("smtp.example.com");
+If you're not familiar with dependency injection then you can specify the SMTP host address like this:
+
+```csharp
+using var smtpSender = SmtpSender.Create("smtp.example.com");
 ```
 
+An email sender must have a SMTP host address, and sometimes a port number, but leaving the port as the default value of 0 will normally choose the right port automatically (e.g. 25). Most companies use LDAP or something similar for behind-the-scenes authentication, but if not you can specify a network credential too.
+
 ### Sending Mail
 
-```
+```csharp
 var email = smtpSender.WriteEmail
     .From("me@example.com")
     .To("you@example.com")
@@ -23,17 +31,16 @@ var email = smtpSender.WriteEmail
 await email.SendAsync();
 ```
 
-An email must have a SMTP host address, a `From` and at least one `To` address; that's all. You can use each method as many times as you want, but setting a subject or body multiple times will overwrite previous subject or body values. The order of anything after WriteEmail does not matter.
-Any issues will throw an exception, but you can also opt to just log them and continue with a `false` output:
+Any configuration issues will throw an exception, but you can also opt to just log any exceptions and continue with a `false` output:
 
-```
+```csharp
 bool isSent = await smtpSender.WriteEmail
     .From("me@example.com", "My Name")
     .To("you@example.com", "Your Name")
-    .To("friend1@example.com")
-    .To("friend2@example.com")
+    .Cc("friend1@example.com")
+    .Bcc("friend2@example.com")
     .Subject("Hey You")
-    .Body($"Hello! {DateTime.Now}")
+    .Body($"Hello at {DateTime.Now}.")
     .Attach("C:/Temp/attachment1.txt", "C:/Temp/attachment2.pdf")
     .Attach("./attachment3.docx")
     .TrySendAsync();
@@ -46,7 +53,8 @@ Further examples (detailed MailKit SMPT server logs etc.) can be found in MailKi
 ### Dependency Injection
 
 This is recommended over manual setup as the built-in garbage collector will handle lifetime and disposal.
-```
+
+```csharp
 using MailKitSimplified.Sender.Extensions;
 
 IHost host = Host.CreateDefaultBuilder(args)
@@ -61,75 +69,61 @@ await host.RunAsync();
 ```
 
 You'll also need the following in appsettings.json:
-```
+
+```json
 {
   "EmailSender:SmtpHost": "smtp.example.com"
 }
 ```
 
 Other optional settings include SmtpPort, ProtocolLog, SmtpCredential:UserName and SmtpCredential:Password.
 
-Now you can use the fully configured IEmailSender anywhere you want with no other setup! For example:
-
-```
-public class EmailService {
-
-    private readonly IEmailSender _smtpSender;
-
-    public EmailService(IEmailSender smtpSender) {
-        _smtpSender = smtpSender;
-    }
-}
-```
-
-Or, even easier, just start with IEmailWriter:
-
-```
-public class EmailService {
+Now you can use the fully configured IEmailSender or IEmailWriter anywhere you want with no other setup! For example:
 
+```csharp
+public class EmailService
+{
     private readonly IEmailWriter _writeEmail;
 
     public EmailService(IEmailWriter emailWriter) {
         _writeEmail = emailWriter;
     }
-
-    public async Task SendTestEmailAsync(string bodyText = "") {
-        await _writeEmail
-            .From("me@example.com")
-            .To("you@example.com")
-            .Subject("Test email")
-            .Body(bodyText)
-            .SendAsync();
-    }
 }
 ```
 
-## Receiver Usage
+That's how sending an email can become as simple as one line of code.
+
+```csharp
+await _writeEmail.To("test@localhost").SendAsync();
+```
+
+## MailKitSimplified.Receiver Usage
 
 ### Setup
 
 If you're not familiar with dependency injection then just use this:
-```
-using var imapReceiver = MimeMessageReceiver.Create("imap.example.com", 0, "U5ern@me", "P@55w0rd");
+
+```csharp
+using var imapReceiver = ImapReceiver.Create("imap.example.com", 0, "U5ern@me", "P@55w0rd");
 ```
 
-An email receiver must have a IMAP host address, a network credential, and a valid mail folder to read from.
+An email receiver must have a IMAP host address, a network credential (unless you're using something like `smtp4dev`), and sometimes a port number, but leaving the port as the default value of 0 will normally choose the right port automatically.
 
 ### Receiving Mail
 
-```
+```csharp
 var mailboxReceiver = imapReceiver
     .ReadFrom("INBOX")
     .Skip(0)
     .Take(10);
 
-await mailboxReceiver.GetMimeMessagesAsync();
+var mimeMessages = await mailboxReceiver.GetMimeMessagesAsync();
 ```
 
-```
+```csharp
 var mimeMessageQueue = await imapReceiver
     .ReadFrom("INBOX")
     .GetMimeMessagesAsync();
 ```
 
-Further examples (detailed MailKit IMAP server logs etc.) can be found in MailKitSimplifiedReceiverUnitTests and the example solution file.
+Further examples (detailed MailKit IMAP server logs etc.) can be found in the 'samples' and 'tests' folders.

samples/ConsoleServiceExample/Program.cs

@@ -8,15 +8,15 @@
 using var loggerFactory = LoggerFactory.Create(_ => _.SetMinimumLevel(LogLevel.Trace).AddDebug().AddConsole());
 var logger = loggerFactory.CreateLogger<Program>();
 
-using var smtpSender = MimeMessageSender.Create("localhost", 25);
-bool isSent = await Email.Create(smtpSender)
+using var smtpSender = SmtpSender.Create("localhost", 25);
+bool isSent = await smtpSender.WriteEmail
     .Bcc($"{Guid.NewGuid():N}@localhost")
     .TrySendAsync();
 
 logger.LogInformation("Email {result}.", isSent ? "sent" : "failed to send");
 
-using var imapReceiver = ImapClientService.Create("localhost", null, 143);
-var messages = await MailFolderReader.Create("INBOX", imapReceiver)
+using var imapReceiver = ImapReceiver.Create("localhost", null, 143);
+var messageSummaries = await imapReceiver.ReadFrom("INBOX")
     .GetMessageSummariesAsync(MessageSummaryItems.UniqueId);
 
-logger.LogDebug($"Email received: {messages.Select(m => m.UniqueId).ToEnumeratedString()}");
+logger.LogDebug("Email(s) received: {ids}", messageSummaries.Select(m => m.UniqueId).ToEnumeratedString());

source/MailKitSimplified.Core/Abstractions/IEmailSender.cs

@@ -1,12 +1,15 @@
-using System.Threading;
+using System;
+using System.Threading;
 using System.Threading.Tasks;
 
 namespace MailKitSimplified.Core.Abstractions
 {
-    public interface IEmailSender
+    public interface IEmailSender : IDisposable
     {
         IEmailWriter WriteEmail { get; }
+
         Task SendAsync(ISendableEmail email, CancellationToken cancellationToken = default);
+
         Task<bool> TrySendAsync(ISendableEmail email, CancellationToken cancellationToken = default);
     }
 }

source/MailKitSimplified.Core/Models/EmailSenderOptions.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Net;
 using System.ComponentModel.DataAnnotations;
+using MailKitSimplified.Core.Abstractions;
 
 namespace MailKitSimplified.Core.Models
 {

source/MailKitSimplified.Receiver/Abstractions/IEmailReader.cs

@@ -0,0 +1,17 @@
+using MailKit;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace MailKitSimplified.Receiver.Abstractions
+{
+    public interface IEmailReader
+    {
+        IEmailReader MailFolderName(string mailFolderName);
+
+        IEmailReader Skip(int count);
+
+        IEmailReader Take(int count);
+
+        ValueTask<IMailFolder> ConnectAsync(CancellationToken cancellationToken = default);
+    }
+}

…eiver/Abstractions/IImapClientService.cs …d.Receiver/Abstractions/IImapReceiver.cssource/MailKitSimplified.Receiver/Abstractions/IImapClientService.cs renamed to source/MailKitSimplified.Receiver/Abstractions/IImapReceiver.cs source/MailKitSimplified.Receiver/Abstractions/IImapClientService.cs renamed to source/MailKitSimplified.Receiver/Abstractions/IImapReceiver.cs

@@ -5,7 +5,7 @@
 
 namespace MailKitSimplified.Receiver.Abstractions
 {
-    public interface IImapClientService : IDisposable
+    public interface IImapReceiver : IDisposable
     {
         ValueTask<IMailFolder> ConnectAsync(CancellationToken cancellationToken = default);
         ValueTask<IMailFolder> GetFolderAsync(string mailFolderName, CancellationToken ct = default);

source/MailKitSimplified.Receiver/Extensions/DependencyInjectionExtensions.cs

@@ -14,7 +14,7 @@ public static IServiceCollection AddMailKitSimplifiedEmailReceiver(this IService
             // This adds IOptions<EmailReceiverOptions> from appsettings.json
             services.Configure<EmailReceiverOptions>(configSection);
             services.AddTransient<IMailFolderReader, MailFolderReader>();
-            services.AddTransient<IImapClientService, ImapClientService>();
+            services.AddTransient<IImapReceiver, ImapReceiver>();
             return services;
         }
     }

…d.Receiver/Services/ImapClientService.cs …lified.Receiver/Services/ImapReceiver.cssource/MailKitSimplified.Receiver/Services/ImapClientService.cs renamed to source/MailKitSimplified.Receiver/Services/ImapReceiver.cs source/MailKitSimplified.Receiver/Services/ImapClientService.cs renamed to source/MailKitSimplified.Receiver/Services/ImapReceiver.cs

@@ -18,15 +18,15 @@
 
 namespace MailKitSimplified.Receiver.Services
 {
-    public class ImapClientService : IImapClientService
+    public class ImapReceiver : IImapReceiver
     {
         private readonly ILogger _logger;
         private readonly IImapClient _imapClient;
         private readonly EmailReceiverOptions _receiverOptions;
 
-        public ImapClientService(IOptions<EmailReceiverOptions> receiverOptions, IProtocolLogger protocolLogger = null, ILogger<ImapClientService> logger = null)
+        public ImapReceiver(IOptions<EmailReceiverOptions> receiverOptions, IProtocolLogger protocolLogger = null, ILogger<ImapReceiver> logger = null)
         {
-            _logger = logger ?? NullLogger<ImapClientService>.Instance;
+            _logger = logger ?? NullLogger<ImapReceiver>.Instance;
             _receiverOptions = receiverOptions.Value;
             if (string.IsNullOrWhiteSpace(_receiverOptions.ImapHost))
                 throw new NullReferenceException(nameof(EmailReceiverOptions.ImapHost));
@@ -36,27 +36,33 @@ public ImapClientService(IOptions<EmailReceiverOptions> receiverOptions, IProtoc
             _imapClient = imapLogger != null ? new ImapClient(imapLogger) : new ImapClient();
         }
 
-        public static ImapClientService Create(string imapHost, ushort imapPort = 0, string username = null, string password = null, string protocolLog = null)
+        public static ImapReceiver Create(string imapHost, ushort imapPort = 0, string username = null, string password = null, string protocolLog = null)
         {
             var imapCredential = username == null && password == null ? null : new NetworkCredential(username ?? "", password ?? "");
             var receiver = Create(imapHost, imapCredential, imapPort, protocolLog);
             return receiver;
         }
 
-        public static ImapClientService Create(string imapHost, NetworkCredential imapCredential, ushort imapPort = 0, string protocolLog = null)
+        public static ImapReceiver Create(string imapHost, NetworkCredential imapCredential, ushort imapPort = 0, string protocolLog = null)
         {
             var receiverOptions = new EmailReceiverOptions(imapHost, imapCredential, imapPort, protocolLog);
             var receiver = Create(receiverOptions);
             return receiver;
         }
 
-        public static ImapClientService Create(EmailReceiverOptions emailReceiverOptions)
+        public static ImapReceiver Create(EmailReceiverOptions emailReceiverOptions)
         {
             var options = Options.Create(emailReceiverOptions);
-            var receiver = new ImapClientService(options);
+            var receiver = new ImapReceiver(options);
             return receiver;
         }
 
+        public MailFolderReader ReadFrom(string mailFolderName)
+        {
+            var mailboxReceiver = MailFolderReader.Create(mailFolderName, this);
+            return mailboxReceiver;
+        }
+
         /// <exception cref="AuthenticationException">Failed to authenticate</exception>
         public virtual async ValueTask AuthenticateAsync(CancellationToken cancellationToken = default)
         {

source/MailKitSimplified.Receiver/Services/MailFolderReader.cs

@@ -23,23 +23,23 @@ public class MailFolderReader : IMailFolderReader
         public int FolderCount => _mailFolder?.Count ?? 0;
 
         private readonly ILogger _logger;
-        private readonly IImapClientService _imapClientService;
+        private readonly IImapReceiver _imapClientService;
         private IMailFolder _mailFolder;
 
-        public MailFolderReader(IImapClientService imapClientService, ILogger<MailFolderReader> logger = null)
+        public MailFolderReader(IImapReceiver imapClientService, ILogger<MailFolderReader> logger = null)
         {
             _logger = logger ?? NullLogger<MailFolderReader>.Instance;
             _imapClientService = imapClientService ?? throw new ArgumentNullException(nameof(imapClientService));
         }
 
         public static MailFolderReader Create(string folderName, EmailReceiverOptions emailReceiverOptions)
         {
-            var imapClientService = ImapClientService.Create(emailReceiverOptions);
+            var imapClientService = ImapReceiver.Create(emailReceiverOptions);
             var mailFolderReader = Create(folderName, imapClientService);
             return mailFolderReader;
         }
 
-        public static MailFolderReader Create(string folderName, IImapClientService imapClientService)
+        public static MailFolderReader Create(string folderName, IImapReceiver imapClientService)
         {
             var mailFolderReader = new MailFolderReader(imapClientService);
             mailFolderReader._mailFolder = imapClientService.GetFolderAsync(folderName).GetAwaiter().GetResult();