Merge latest main

Author: zhaparoff

.editorconfig

@@ -52,7 +52,8 @@ trim_trailing_whitespace = false
 [*.cs]
 
 # License header
-file_header_template = -----------------------------------------------------------------------\n<copyright file="{fileName}" company="Railsware Products Studio, LLC">\nCopyright (c) Railsware Products Studio, LLC. All rights reserved.\n</copyright>\n-----------------------------------------------------------------------
+file_header_template = unset
+# -----------------------------------------------------------------------\n<copyright file="{fileName}" company="Railsware Products Studio, LLC">\nCopyright (c) Railsware Products Studio, LLC. All rights reserved.\n</copyright>\n-----------------------------------------------------------------------
 
 # New line preferences
 csharp_new_line_before_open_brace = all
@@ -98,6 +99,7 @@ csharp_prefer_simple_using_statement = true:suggestion
 csharp_style_prefer_switch_expression = true:suggestion
 csharp_style_namespace_declarations = file_scoped:suggestion
 dotnet_style_readonly_field = true:suggestion
+dotnet_style_require_accessibility_modifiers = always:suggestion
 
 # Expression-level preferences
 dotnet_style_object_initializer = true:suggestion
@@ -111,6 +113,7 @@ dotnet_style_prefer_inferred_anonymous_type_member_names = true:suggestion
 dotnet_style_prefer_auto_properties = true:suggestion
 dotnet_style_prefer_conditional_expression_over_assignment = true:silent
 dotnet_style_prefer_conditional_expression_over_return = true:silent
+dotnet_style_prefer_collection_expression = false:suggestion
 csharp_prefer_simple_default_expression = true:suggestion
 csharp_style_prefer_top_level_statements = true:silent
 
@@ -274,7 +277,7 @@ dotnet_diagnostic.IDE0045.severity = suggestion
 dotnet_diagnostic.IDE0046.severity = suggestion
 
 # IDE0058: Expression value is never used
-dotnet_diagnostic.IDE0058.severity = suggestion
+dotnet_diagnostic.IDE0058.severity = silent
 
 
 # CA1032: Implement standard exception constructors

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# These owners will be the default owners for everything in
+# the repo. Unless a later match takes precedence, they will be
+# requested for review when someone opens a pull request.
+*       @zhaparoff @mklocek @vittorius

.github/pull_request_template.md

@@ -1,15 +1,22 @@
 ## Motivation
 
 
-## Description of Changes
-
-
-## Checklist
-- [ ] Acknowledged that contribution is made under the project's [LICENSE](https://github.com/mailtrap/mailtrap-dotnet/blob/main/LICENSE.md)
-- [ ] Confirmed that PR and code/documentation changes are following the [Contributor Code of Conduct](https://github.com/mailtrap/mailtrap-dotnet/blob/main/CODE_OF_CONDUCT.md)
-- [ ] PR is properly titled and contains the summary of changes introduced
-- [ ] PR branch is based on the latest main branch commit
-- [ ] PR contains some meaningful changes, including, but not limited to: functionality, tests, documentation, spelling, etc.
-- [ ] Added/updated XMLDoc and inline comments in the code, according to the changes made
-- [ ] Added/updated unit tests for added/changed functionality (if any)
-- [ ] Added/updated documentation files (if applicable)
+## Changes
+
+- Change 1
+- Change 2
+
+## How to test
+
+- [ ] Test 1
+- [ ] Test 2
+
+## Images and GIFs
+
+| Before | After  |
+|--------|--------|
+| link1  | link2  |
+| link3  | link4  |
+| link5  | link6  |
+| link7  | link8  |
+| link9  | link10 |

CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing to Mailtrap .NET Client
+First of all, thank you for considering contributing to Mailtrap .NET Client!  
+We are excited to have you here :tada:  
+Any contribution is welcome and appreciated, be it a bug report, a feature request, a documentation update, or a code change.
+
+
+## Code of Conduct
+This project and everyone participating in it is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).  
+By participating, you are expected to uphold this code.  
+Please report unacceptable behavior to [[email protected]](mailto:[email protected]).
+
+
+## License
+This project is licensed under the [MIT License](LICENSE.md).  
+Please consider that your contributions should meet its terms and conditions.  
+Also, by participating, you give your permission to license your contributions into this project under its terms and conditions.
+
+
+## Report an issue or propose improvement
+Kindly consider searching for already existing issue or feature proposal before creating a new one.  
+Do not increase the entropy unnecessarily - the Universe will appreciate it.
+
+If it is still the case - please use [Issues](https://github.com/railsware/mailtrap-dotnet/issues) section of the repo to file an issue, 
+possible improvement or feature proposal.  
+
+
+## Contribute to the code or documentation
+
+### Prerequisites
+To be able to make edits, build and run your changes locally, you will need the following:
+- Code editor or IDE of your choice, with C# language and .NET 9.x support.  
+This repository uses [EditorConfig](https://aka.ms/editorconfigdocs) settings to enforce consistent code style, 
+thus usage of editor which respects them is highly encouraged.  
+[Visual Studio 2022](https://visualstudio.microsoft.com/) is one of recommended options.  
+
+- [.NET SDK v9.x](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)
+
+- Plain text editor of your choice - for documentation updates.  
+Ideally, with [Markdown](https://en.wikipedia.org/wiki/Markdown) support.
+
+- [docfx](https://dotnet.github.io/docfx/docs/) - to build and validate documentation website.
+
+
+### Pull requests
+Please consider that contributions to the repository content are managed through pull requests.  
+Thus you will need to follow steps below to create a new one:  
+
+1. Clone the repo
+```bat
+git clone https://github.com/railsware/mailtrap-dotnet.git
+```
+
+2. Create new branch
+```bat
+git checkout -b <branch-name>
+```
+Please consider using the following pattern for branch naming:  
+`[change-type]/[issue-id]-[change-description]`  
+where:  
+`[change-type]` - one of the following: `feat[ure]`, `fix`, `docs`, `devops`, `test`, `refactor`, etc.  
+`[issue-id]` - numeric ID of the issue that you are going to address, if available.  
+`[change-description]` - short description of the change, in [kebab-case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case)
+
+3. Make changes, validate them.
+
+4. Create commits with a description of changes made.  
+Usage of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) is encouraged.
+
+5. Push to the remote.
+
+6. Finally, create a pull request to the [main](https://github.com/railsware/mailtrap-dotnet/tree/main) branch, 
+using the template provided.  
+Please consider providing detailed description what was changed and validating PR checklist to streamline the PR review.
+
+
+### Code
+This SDK is targeting [.NET Standard 2.0](https://dotnet.microsoft.com/platform/dotnet-standard#versions)
+thus not all latest C# language features are supported.  
+Only C# v7.3 features support is guaranteed.  
+Later version features should be used with care and their runtime behavior should be thoroughly tested.
+
+Adding unit/integration tests is encouraged for every added/changed functionality.  
+Although we are not targeting 100% coverage, ensuring everything is working as expected is important.
+
+
+### Documentation
+You can improve SDK documentation in several ways.
+
+#### Add or extend [XMLDoc](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) comments in the code
+They are used to show inline help in IDE and to generate SDK API reference section of documentation website,
+thus are a crucial part of the SDK.
+
+#### Update markdown files in the [docs](https://github.com/railsware/mailtrap-dotnet/tree/main/docs) folder of the repo.  
+Considering that [docfx](https://dotnet.github.io/docfx/docs/basic-concepts.html) tool is used to create documentation website
+from sources, please ensure that you are using [supported syntax](https://dotnet.github.io/docfx/docs/markdown.html).
+
+To build and verify documentation locally, before committing your changes:
+1. Install/update `docfx` as a global tool
+```bat
+dotnet tool (install|update) -g docfx
+```
+2. Build and serve documentation website
+```bat
+cd <repository-path>
+docfx docs/docfx.json --serve
+```
+3. Finally, open <http://localhost:8080> in your browser and navigate to the changed section.

Directory.Packages.props

@@ -5,26 +5,26 @@
   <ItemGroup>
     <!-- MS -->
     <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0" />
-    <PackageVersion Include="Microsoft.DotNet.ApiCompat.Task" Version="9.0.101" />
-    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="9.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Http" Version="9.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="9.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="9.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="9.0.7" />
+    <PackageVersion Include="Microsoft.Extensions.Http" Version="9.0.7" />
+    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="9.7.0" />
+    <PackageVersion Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="9.0.7" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
     <PackageVersion Include="System.Net.Http.Json" Version="8.0.1" />
-    <PackageVersion Include="System.Text.Json" Version="9.0.0" />
+    <PackageVersion Include="System.Text.Json" Version="9.0.7" />
     <!-- 3rd party -->
     <PackageVersion Include="FluentValidation" Version="11.11.0" />
-    <PackageVersion Include="MinVer" Version="6.0.0" />
-    <!--Testing -->
-    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
-    <PackageVersion Include="NUnit" Version="4.2.2" />
-    <PackageVersion Include="NUnit.Analyzers" Version="4.4.0" />
-    <PackageVersion Include="NUnit3TestAdapter" Version="4.6.0" />
-    <PackageVersion Include="coverlet.collector" Version="6.0.2" />
+    <!-- Testing -->
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageVersion Include="NUnit" Version="4.3.2" />
+    <PackageVersion Include="NUnit.Analyzers" Version="4.9.2" />
+    <PackageVersion Include="NUnit3TestAdapter" Version="5.0.0" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.4" />
     <PackageVersion Include="Moq" Version="4.20.72" />
     <PackageVersion Include="RichardSzalay.MockHttp" Version="7.0.0" />
-    <PackageVersion Include="FluentAssertions" Version="7.0.0" />
+    <!-- Do NOT update FluentAssertions to major version 8 and above, since it does not provide permissive license anymore -->
+    <!-- https://github.com/fluentassertions/fluentassertions/issues/2955 -->
+    <PackageVersion Include="FluentAssertions" Version="7.2.0" />
     <PackageVersion Include="FluentAssertions.Analyzers" Version="0.34.1" />
   </ItemGroup>
 </Project>

Mailtrap.sln

@@ -54,6 +54,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{CD08E7CB-C
 	ProjectSection(SolutionItems) = preProject
 		CHANGELOG.md = CHANGELOG.md
 		CODE_OF_CONDUCT.md = CODE_OF_CONDUCT.md
+		CONTRIBUTING.md = CONTRIBUTING.md
 		LICENSE.md = LICENSE.md
 		README.md = README.md
 	EndProjectSection

README.md

@@ -1,9 +1,123 @@
-# Official Mailtrap .NET Client
+![Mailtrap](assets/img/mailtrap-logo.svg)
 
+[![NuGet Version](https://img.shields.io/nuget/v/Railsware.Mailtrap?label=NuGet)](https://www.nuget.org/packages/Railsware.Mailtrap)
 [![CI](https://github.com/railsware/mailtrap-dotnet/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/railsware/mailtrap-dotnet/actions/workflows/build.yml)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/railsware/mailtrap-dotnet/blob/main/LICENSE.md)
 
-## Summary
-This is the official .NET client for [Mailtrap](https://mailtrap.io/)
+# Official Mailtrap .NET Client
+Welcome to the official [Mailtrap](https://mailtrap.io/) .NET Client repository.  
+This client allows you to quickly and easily integrate your .NET application with **v2.0** of the [Mailtrap API](https://api-docs.mailtrap.io/docs/mailtrap-api-docs/5tjdeg9545058-mailtrap-api).
+
+
+## Quick Start
+The following few simple steps will bring Mailtrap API functionality into your .NET project.
+
+### Prerequisites
+- Please ensure your project targets .NET implementation which supports [.NET Standard 2.0](https://dotnet.microsoft.com/platform/dotnet-standard#versions) specification.
+
+- Register new or log into existing account at [mailtrap.io](https://mailtrap.io/register/signup?ref=maitrap-dotnet)
+
+- Obtain [API token](https://mailtrap.io/api-tokens)  
+  You can use one of the existing or create a new one.
+
+### Install
+Install `Mailtrap` package from NuGet  
+
+  > **TODO**  
+  > This is an example command, to be updated once the package is published.  
+
+  ```console
+  dotnet add package Mailtrap
+  ```
+
+### Configure
+Add Mailtrap services to the DI container.
+
+```csharp
+using Mailtrap;
+   
+...
+   
+hostBuilder.ConfigureServices((context, services) =>
+{
+   services.AddMailtrapClient(options =>
+   {
+      // Definitely, hardcoding a token isn't a good idea.
+      // This example uses it for simplicity, but in real-world scenarios
+      // you should consider more secure approaches for storing secrets.
+         
+      // Environment variables can be an option, as well as other solutions:
+      // https://learn.microsoft.com/aspnet/core/security/app-secrets
+      // or https://learn.microsoft.com/aspnet/core/security/key-vault-configuration
+      options.ApiToken = "<API_TOKEN>";
+   });
+});   
+```
+
+### Use
+Now you can inject `IMailtrapClient` instance in any application service and use it to make API calls.
+
+```csharp
+using Mailtrap;
+using Mailtrap.Emails.Requests;
+using Mailtrap.Emails.Responses;
+   
+
+namespace MyAwesomeProject;
+
+
+public sealed class SendEmailService : ISendEmailService
+{
+    private readonly IMailtrapClient _mailtrapClient;
+
+
+    public SendEmailService(IMailtrapClient mailtrapClient)
+    {
+        _mailtrapClient = client;
+    }
+
+
+    public async Task DoWork()
+    {
+        try 
+        {
+            SendEmailRequest request = SendEmailRequest
+                .Create()
+                .From("[email protected]", "John Doe")
+                .To("[email protected]")
+                .Subject("Invitation to Earth")
+                .Text("Dear Bill,\n\nIt will be a great pleasure to see you on our blue planet next weekend.\n\nBest regards, John.");
+
+            SendEmailResponse response = await _mailtrapClient
+                .Email()
+                .Send(request);
+                
+            string messageId = response.MessageIds.FirstOrDefault();
+        }
+        catch (MailtrapException mtex)
+        {
+            // handle Mailtrap API specific exceptions
+        }
+        catch (OperationCancelledException ocex)
+        {
+            // handle cancellation
+        }
+        catch (Exception ex)
+        {
+            // handle other exceptions
+        }   
+    }
+}
+```
+
+## Documentation
+Please visit [Documentation Portal](https://railsware.github.io/mailtrap-dotnet/) for detailed setup, configuration and usage instructions.  
+A bunch of examples is available [here](https://github.com/railsware/mailtrap-dotnet/tree/main/examples).
+
+
+## Contributing
+We believe in the power of OSS and welcome any contributions to the library.  
+Please refer to [Contributing Guide](CONTRIBUTING.md) for details.
 
-It works with the second version of [Mailtrap API](https://api-docs.mailtrap.io/docs/mailtrap-api-docs/5tjdeg9545058-mailtrap-api)
+## License
+Licensed under the [MIT License](LICENSE.md).

docs/cookbook/send-email.md

@@ -40,6 +40,7 @@ var from = new EmailAddress("[email protected]", "John Doe");
 var request = new SendEmailRequest
 {
     From = from,
+    ReplyTo = new EmailAddress("[email protected]"),
     Subject = "Invitation to Earth",
     TextBody = "Dear Bill,\n\nIt will be a great pleasure to see you on our blue planet next weekend.\n\nBest regards, John."
 };
@@ -130,6 +131,9 @@ var request = SendEmailRequest.Create();
 // Sender (Display name is optional)
 request.From("[email protected]", "John Doe");
 
+// Reply To (Display name is optional)
+request.ReplyTo("[email protected]");
+
 // You can use simple email as recipient
 request.To("[email protected]");