diff --git a/.github/workflows/validate-nuget-publish.yml b/.github/workflows/validate-nuget-publish.yml index ed353a6..9f8979c 100644 --- a/.github/workflows/validate-nuget-publish.yml +++ b/.github/workflows/validate-nuget-publish.yml @@ -1,13 +1,12 @@ name: Validate NuGet Publish -# Temporarily commented out until making it a fully compliant OSS module. -## on: -## pull_request: -## push: -## branches: -## - dev -## -## jobs: -## validate-nuget-publish: -## name: Validate NuGet Publish -## uses: Lombiq/GitHub-Actions/.github/workflows/validate-nuget-publish.yml@dev +on: + pull_request: + push: + branches: + - dev + +jobs: + validate-nuget-publish: + name: Validate NuGet Publish + uses: Lombiq/GitHub-Actions/.github/workflows/validate-nuget-publish.yml@dev diff --git a/Lombiq.EmailClient.Samples/Controllers/EmailSyncController.cs b/Lombiq.EmailClient.Samples/Controllers/EmailSyncController.cs new file mode 100644 index 0000000..9f0700b --- /dev/null +++ b/Lombiq.EmailClient.Samples/Controllers/EmailSyncController.cs @@ -0,0 +1,30 @@ +using Lombiq.EmailClient.Services; +using Microsoft.AspNetCore.Mvc; +using Microsoft.Extensions.DependencyInjection; +using OrchardCore.BackgroundJobs; +using System.Threading.Tasks; + +namespace Lombiq.EmailClient.Samples.Controllers; + +// If the Email Sync feature is enabled, a background task automatically fetches emails from the configured IMAP server. +// An email sync event handler can be implemented to process these emails (you'll see it shortly). You can trigger the +// email sync manually by using the IEmailSyncService service. This controller demonstrates how to do that. +public class EmailSyncController : Controller +{ + public async Task Index() + { + // The email sync operation might take a while so it's recommended to run it after the request. + await HttpBackgroundJob.ExecuteAfterEndOfRequestAsync(nameof(EmailSyncController), scope => + { + var service = scope.ServiceProvider.GetService(); + + // This method fetches the next batch of emails from the IMAP server. When it syncs an email it calls the + // EmailSyncedAsync method of the registered email sync event handlers. + return service.SyncNextEmailsAsync(); + }); + + return Ok(); + } +} + +// NEXT STATION: Services/SampleEmailSyncEventHandler.cs diff --git a/Lombiq.EmailClient.Samples/Controllers/ImapController.cs b/Lombiq.EmailClient.Samples/Controllers/ImapController.cs new file mode 100644 index 0000000..d2dee50 --- /dev/null +++ b/Lombiq.EmailClient.Samples/Controllers/ImapController.cs @@ -0,0 +1,31 @@ +using Lombiq.EmailClient.Models; +using Lombiq.EmailClient.Services; +using Microsoft.AspNetCore.Mvc; +using System.Threading.Tasks; + +namespace Lombiq.EmailClient.Samples.Controllers; + +// This controller demonstrates how to fetch emails from an IMAP server. +public class ImapController : Controller +{ + // The IEmailClient service is used to fetch emails. Check the interface to see what you can do with it. + private readonly IEmailClient _emailClient; + + public ImapController(IEmailClient emailClient) => + _emailClient = emailClient; + + public async Task Index() + { + // You can filter emails by subject. For testing purposes we filter by "important". + var parameters = new EmailFilterParameters + { + Subject = "important", + }; + + // Fetch emails from the IMAP server. + var emails = await _emailClient.GetEmailsAsync(parameters); + + // NEXT STATION: Go to Views/Imap/Index.cshtml. + return View(emails); + } +} diff --git a/Lombiq.EmailClient.Samples/Lombiq.EmailClient.Samples.csproj b/Lombiq.EmailClient.Samples/Lombiq.EmailClient.Samples.csproj new file mode 100644 index 0000000..8f1ac47 --- /dev/null +++ b/Lombiq.EmailClient.Samples/Lombiq.EmailClient.Samples.csproj @@ -0,0 +1,37 @@ + + + + net8.0 + true + + + + + + + + Lombiq Email Client for Orchard Core - Samples + Lombiq Technologies + Copyright © 2025, Lombiq Technologies Ltd. + Lombiq Email Client for Orchard Core - Samples: Sample content that demonstrates the features of Lombiq Email Client module for Orchard Core. + NuGetIcon.png + OrchardCore;Lombiq;AspNetCore;Emails;IMAP + https://github.com/Lombiq/Orchard-Email-Client + https://github.com/Lombiq/Orchard-Email-Client/blob/dev/Lombiq.EmailClient.Samples/Readme.md + BSD-3-Clause + + + + + + + + + + + + + + + + diff --git a/Lombiq.EmailClient.Samples/Manifest.cs b/Lombiq.EmailClient.Samples/Manifest.cs new file mode 100644 index 0000000..13b57ec --- /dev/null +++ b/Lombiq.EmailClient.Samples/Manifest.cs @@ -0,0 +1,15 @@ +using OrchardCore.Modules.Manifest; +using static Lombiq.EmailClient.Constants.FeatureIds; + +[assembly: Module( + Name = "Lombiq Email Client - Samples", + Author = "Lombiq Technologies", + Website = "https://github.com/Lombiq/Orchard-Email-Client", + Version = "0.0.1", + Description = "Samples for Lombiq Email Client.", + Category = "Email", + Dependencies = [ + Imap, + EmailSync + ] +)] diff --git a/Lombiq.EmailClient.Samples/NuGetIcon.png b/Lombiq.EmailClient.Samples/NuGetIcon.png new file mode 100644 index 0000000..162a005 Binary files /dev/null and b/Lombiq.EmailClient.Samples/NuGetIcon.png differ diff --git a/Lombiq.EmailClient.Samples/Readme.md b/Lombiq.EmailClient.Samples/Readme.md new file mode 100644 index 0000000..a9ba6d9 --- /dev/null +++ b/Lombiq.EmailClient.Samples/Readme.md @@ -0,0 +1,22 @@ +# Lombiq Email Client for Orchard Core - Samples + +## About + +Example Orchard Core module that makes use of Lombiq Email Client for Orchard Core. + +For general details about and usage instructions see the [root Readme](../Readme.md). + +Do you want to quickly try out this project and see it in action? Check it out in our [Open-Source Orchard Core Extensions](https://github.com/Lombiq/Open-Source-Orchard-Core-Extensions) full Orchard Core solution and also see our other useful Orchard Core-related open-source projects! + +## Training sections + +You can start with any of these sections, they demonstrate different approaches that best fit different use-cases. + +- [Fetching emails from IMAP](../Lombiq.EmailClient.Samples/Controllers/ImapController.cs) +- [Email sync](../Lombiq.EmailClient.Samples/Controllers/EmailSyncController.cs) + +## Contributing and support + +Bug reports, feature requests, comments, questions, code contributions and love letters are warmly welcome. You can send them to us via GitHub issues and pull requests. Please adhere to our [open-source guidelines](https://lombiq.com/open-source-guidelines) while doing so. + +This project is developed by [Lombiq Technologies](https://lombiq.com/). Commercial-grade support is available through Lombiq. diff --git a/Lombiq.EmailClient.Samples/Recipes/Lombiq.EmailClient.Samples.recipe.json b/Lombiq.EmailClient.Samples/Recipes/Lombiq.EmailClient.Samples.recipe.json new file mode 100644 index 0000000..e795832 --- /dev/null +++ b/Lombiq.EmailClient.Samples/Recipes/Lombiq.EmailClient.Samples.recipe.json @@ -0,0 +1,32 @@ +{ + "name": "Lombiq.EmailClient.Samples", + "displayName": "Lombiq Email Client - Samples", + "description": "Sample feature utilizing the Lombiq Email Client feature.", + "author": "Lombiq Technologies", + "website": "https://github.com/Lombiq/Orchard-Chart.js", + "version": "1.0", + "issetuprecipe": false, + "categories": [ + "training" + ], + "tags": [ + "developer", + "training", + "sample" + ], + "steps": [ + { + "name": "feature", + "enable": [ + "Lombiq.EmailClient.Samples" + ] + }, + { + "name": "Settings", + "ImapSettings": { + "Host": "127.0.0.1", + "Port": 143 + } + } + ] +} diff --git a/Lombiq.EmailClient.Samples/Services/SampleEmailSyncEventHandler.cs b/Lombiq.EmailClient.Samples/Services/SampleEmailSyncEventHandler.cs new file mode 100644 index 0000000..a45d72f --- /dev/null +++ b/Lombiq.EmailClient.Samples/Services/SampleEmailSyncEventHandler.cs @@ -0,0 +1,30 @@ +using Lombiq.EmailClient.Models; +using Lombiq.EmailClient.Services; +using Microsoft.Extensions.Logging; +using System.Threading.Tasks; + +namespace Lombiq.EmailClient.Samples.Services; + +// This is a sample implementation of an email sync event handler. It's called when the Email Sync feature is enabled +// and the background task syncs the next batch of emails (i.e., emails that have been received since the last sync). +public class SampleEmailSyncEventHandler : IEmailSyncEventHandler +{ + private readonly ILogger _logger; + + public SampleEmailSyncEventHandler(ILogger logger) => + _logger = logger; + + public Task EmailSyncedAsync(EmailMessage emailMessage) + { + // For testing purposes we just log the email's subject and sender. However, in a real-world scenario you'd most + // likely want to create a content item that stores the email's data. + _logger.LogDebug( + "Email synced (subject: {Subject}, sender: {Sender})", + emailMessage.Header.Subject, + emailMessage.Header.Sender.Address); + + return Task.CompletedTask; + } +} + +// END OF TRAINING SECTION: Email sync diff --git a/Lombiq.EmailClient.Samples/Startup.cs b/Lombiq.EmailClient.Samples/Startup.cs new file mode 100644 index 0000000..d5fa7c9 --- /dev/null +++ b/Lombiq.EmailClient.Samples/Startup.cs @@ -0,0 +1,12 @@ +using Lombiq.EmailClient.Samples.Services; +using Lombiq.EmailClient.Services; +using Microsoft.Extensions.DependencyInjection; +using OrchardCore.Modules; + +namespace Lombiq.EmailClient.Samples; + +public class Startup : StartupBase +{ + public override void ConfigureServices(IServiceCollection services) => + services.AddScoped(); +} diff --git a/Lombiq.EmailClient.Samples/Views/Imap/Index.cshtml b/Lombiq.EmailClient.Samples/Views/Imap/Index.cshtml new file mode 100644 index 0000000..3f30812 --- /dev/null +++ b/Lombiq.EmailClient.Samples/Views/Imap/Index.cshtml @@ -0,0 +1,27 @@ +@using System.Globalization +@model IEnumerable + +

@T["Important email messages"]

+@T["Email messages where the subject contains the \"important\" word."] + +
    + @* The EmailMessage object has a lot of information about the email, but we're only displaying a few fields here. *@ + @foreach (var emailMessage in Model) + { + + } +
+ +@* END OF TRAINING SECTION: Fetching emails from IMAP server. @* + +@* NEXT STATION: Controllers/EmailSyncController.cs *@ diff --git a/Lombiq.EmailClient.Samples/Views/_ViewImports.cshtml b/Lombiq.EmailClient.Samples/Views/_ViewImports.cshtml new file mode 100644 index 0000000..5d4c60a --- /dev/null +++ b/Lombiq.EmailClient.Samples/Views/_ViewImports.cshtml @@ -0,0 +1,9 @@ +@inherits OrchardCore.DisplayManagement.Razor.RazorPage + +@using OrchardCore +@using OrchardCore.ContentManagement.Display.ViewModels +@using OrchardCore.DisplayManagement.Views + +@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers +@addTagHelper *, OrchardCore.DisplayManagement +@addTagHelper *, OrchardCore.ResourceManagement diff --git a/Lombiq.EmailClient.Tests.UI/Constants/TestEmailPaths.cs b/Lombiq.EmailClient.Tests.UI/Constants/TestEmailPaths.cs new file mode 100644 index 0000000..49d6c81 --- /dev/null +++ b/Lombiq.EmailClient.Tests.UI/Constants/TestEmailPaths.cs @@ -0,0 +1,24 @@ +using System; +using System.IO; + +namespace Lombiq.EmailClient.Tests.UI.Constants; + +public static class TestEmailPaths +{ + private static readonly string BasePath = Path.Combine(Environment.CurrentDirectory, "TestEmails"); + + public static readonly string SampleImportant1FileName = "sample_important_1.eml"; + public static readonly string SampleImportant2FileName = "sample_important_2.eml"; + public static readonly string SampleNotImportantFileName = "sample_not_important.eml"; + + public static readonly string SampleImportant1Path = Path.Combine(BasePath, SampleImportant1FileName); + public static readonly string SampleImportant2Path = Path.Combine(BasePath, SampleImportant2FileName); + public static readonly string SampleNotImportantPath = Path.Combine(BasePath, SampleNotImportantFileName); + + public static readonly string[] SampleEmailPaths = + [ + SampleImportant1Path, + SampleImportant2Path, + SampleNotImportantPath + ]; +} diff --git a/Lombiq.EmailClient.Tests.UI/Extensions/TestCaseUITestContextExtensions.cs b/Lombiq.EmailClient.Tests.UI/Extensions/TestCaseUITestContextExtensions.cs new file mode 100644 index 0000000..e7fe4b4 --- /dev/null +++ b/Lombiq.EmailClient.Tests.UI/Extensions/TestCaseUITestContextExtensions.cs @@ -0,0 +1,25 @@ +using Lombiq.Tests.UI.Extensions; +using Lombiq.Tests.UI.Services; +using OpenQA.Selenium; +using Shouldly; +using System.Threading.Tasks; + +namespace Lombiq.EmailClient.Tests.UI.Extensions; + +public static class TestCaseUITestContextExtensions +{ + public static async Task TestImapEmailFetchingAsync(this UITestContext context) + { + await context.InitSampleEmailsAsync(); + await context.SignInDirectlyAsync(); + await context.ExecuteEmailClientSampleRecipeDirectlyAsync(); + await context.SetImapPortOnAdminAsync(); + await context.GoToImapTestAsync(); + + context.GetAll(By.ClassName("email")).Count.ShouldBe(2); + context.Exists(By.XPath($"//div[contains(text(), 'developer@localhost.com')]")); + context.Exists(By.XPath($"//div[contains(text(), '2025-02-24T12:35:19')]")); + context.Exists(By.XPath($"//div[contains(text(), 'Very important sample')]")); + context.Exists(By.XPath($"//code[contains(text(), 'This email is sent for testing purposes.')]")); + } +} diff --git a/Lombiq.EmailClient.Tests.UI/Extensions/UITestContextExtensions.cs b/Lombiq.EmailClient.Tests.UI/Extensions/UITestContextExtensions.cs new file mode 100644 index 0000000..d4a25ab --- /dev/null +++ b/Lombiq.EmailClient.Tests.UI/Extensions/UITestContextExtensions.cs @@ -0,0 +1,31 @@ +using Lombiq.EmailClient.Samples.Controllers; +using Lombiq.EmailClient.Tests.UI.Constants; +using Lombiq.HelpfulLibraries.OrchardCore.Mvc; +using Lombiq.Tests.UI.Extensions; +using Lombiq.Tests.UI.Services; +using OpenQA.Selenium; +using System; +using System.Threading.Tasks; + +namespace Lombiq.EmailClient.Tests.UI.Extensions; + +public static class UITestContextExtensions +{ + public static Task ExecuteEmailClientSampleRecipeDirectlyAsync(this UITestContext context) => + context.ExecuteRecipeDirectlyAsync("Lombiq.EmailClient.Samples"); + + public static Task InitSampleEmailsAsync(this UITestContext context) => + context.CreateAndUseLocalSmtpClientToSendEmailsFromFilesAsync(TestEmailPaths.SampleEmailPaths); + + public static Task GoToImapTestAsync(this UITestContext context) => + context.GoToAsync(controller => controller.Index()); + + public static async Task SetImapPortOnAdminAsync(this UITestContext context) + { + await context.GoToAdminRelativeUrlAsync("/Settings/ImapSettings"); + await context.FillInWithRetriesAsync( + By.Id("ISite_ImapSettings_Port"), + context.SmtpServiceRunningContext.ImapPort.ToTechnicalString()); + await context.ClickReliablyOnSubmitAsync(); + } +} diff --git a/Lombiq.EmailClient.Tests.UI/Lombiq.EmailClient.Tests.UI.csproj b/Lombiq.EmailClient.Tests.UI/Lombiq.EmailClient.Tests.UI.csproj new file mode 100644 index 0000000..0cc9efd --- /dev/null +++ b/Lombiq.EmailClient.Tests.UI/Lombiq.EmailClient.Tests.UI.csproj @@ -0,0 +1,43 @@ + + + + net8.0 + + + + Lombiq Email Client for Orchard Core - UI Test Extensions + Lombiq Technologies + Copyright © 2025, Lombiq Technologies Ltd. + Lombiq Email Client for Orchard Core - UI Test Extensions: Extension methods that test various features in Lombiq Email Client for Orchard Core. See the project website for detailed documentation. + NuGetIcon.png + OrchardCore;Lombiq;AspNetCore;Email;IMAP;Shouldly;xUnit;UITesting;Testing + https://github.com/Lombiq/Orchard-Email-Client + https://github.com/Lombiq/Orchard-Email-Client/blob/dev/Lombiq.EmailClient.Tests.UI/Readme.md + BSD-3-Clause + + + + + + + + + + + + + + + + + + + + + + PreserveNewest + true + + + + diff --git a/Lombiq.EmailClient.Tests.UI/NuGetIcon.png b/Lombiq.EmailClient.Tests.UI/NuGetIcon.png new file mode 100644 index 0000000..162a005 Binary files /dev/null and b/Lombiq.EmailClient.Tests.UI/NuGetIcon.png differ diff --git a/Lombiq.EmailClient.Tests.UI/Readme.md b/Lombiq.EmailClient.Tests.UI/Readme.md new file mode 100644 index 0000000..e595e1c --- /dev/null +++ b/Lombiq.EmailClient.Tests.UI/Readme.md @@ -0,0 +1,7 @@ +# Lombiq Email Client for Orchard Core - UI Test Extensions + +## About + +Extension methods that test various features in Lombiq Email Client for Orchard Core, with the help of [Lombiq UI Testing Toolbox for Orchard Core](https://github.com/Lombiq/UI-Testing-Toolbox). + +Call these from a UI test project that also references `Lombiq.EmailClient.Samples` to verify the module's basic features; as seen in [Open-Source Orchard Core Extensions](https://github.com/Lombiq/Open-Source-Orchard-Core-Extensions). diff --git a/Lombiq.EmailClient.Tests.UI/TestEmails/sample_important_1.eml b/Lombiq.EmailClient.Tests.UI/TestEmails/sample_important_1.eml new file mode 100644 index 0000000..039257f --- /dev/null +++ b/Lombiq.EmailClient.Tests.UI/TestEmails/sample_important_1.eml @@ -0,0 +1,39 @@ +From: Developer +To: sample@localhost.com +Subject: Very important sample +Date: Mon, 24 Feb 2025 12:35:19 +0000 +Message-Id: +Reply-To: Developer +User-Agent: eM_Client/8.2.1721.0 +Mime-Version: 1.0 +Content-Type: multipart/alternative; + boundary="------=_MB2259ED79-9314-438C-A8B5-7AF6890A524A" + +--------=_MB2259ED79-9314-438C-A8B5-7AF6890A524A +Content-Type: text/plain; charset=utf-8; format=flowed +Content-Transfer-Encoding: quoted-printable + +This email is sent for testing purposes. +--------=_MB2259ED79-9314-438C-A8B5-7AF6890A524A +Content-Type: text/html; charset=utf-8 +Content-Transfer-Encoding: quoted-printable + + + + + +This email is sent for testing purposes. +--------=_MB2259ED79-9314-438C-A8B5-7AF6890A524A-- diff --git a/Lombiq.EmailClient.Tests.UI/TestEmails/sample_important_2.eml b/Lombiq.EmailClient.Tests.UI/TestEmails/sample_important_2.eml new file mode 100644 index 0000000..10c1104 --- /dev/null +++ b/Lombiq.EmailClient.Tests.UI/TestEmails/sample_important_2.eml @@ -0,0 +1,40 @@ +From: Developer +To: sample@localhost.com +Subject: Another important sample +Date: Mon, 24 Feb 2025 12:36:15 +0000 +Message-Id: +Reply-To: Developer +User-Agent: eM_Client/8.2.1721.0 +Mime-Version: 1.0 +Content-Type: multipart/alternative; + boundary="------=_MBDCB289B9-7C7B-46AF-B98D-AAFE8E6A19EB" + +--------=_MBDCB289B9-7C7B-46AF-B98D-AAFE8E6A19EB +Content-Type: text/plain; charset=utf-8; format=flowed +Content-Transfer-Encoding: quoted-printable + +Yet another very important sample email for testing purposes. +--------=_MBDCB289B9-7C7B-46AF-B98D-AAFE8E6A19EB +Content-Type: text/html; charset=utf-8 +Content-Transfer-Encoding: quoted-printable + + + + + +Yet another very important sample email for testing purposes.<= +/html> +--------=_MBDCB289B9-7C7B-46AF-B98D-AAFE8E6A19EB-- diff --git a/Lombiq.EmailClient.Tests.UI/TestEmails/sample_not_important.eml b/Lombiq.EmailClient.Tests.UI/TestEmails/sample_not_important.eml new file mode 100644 index 0000000..7870cae --- /dev/null +++ b/Lombiq.EmailClient.Tests.UI/TestEmails/sample_not_important.eml @@ -0,0 +1,41 @@ +From: Developer +To: "sample@localhost.com" +Subject: Uninteresting sample +Date: Mon, 24 Feb 2025 12:37:07 +0000 +Message-Id: +Reply-To: Developer +User-Agent: eM_Client/8.2.1721.0 +Mime-Version: 1.0 +Content-Type: multipart/alternative; + boundary="------=_MB5D12DEC9-3C13-4205-A6C8-2772BB5E8F57" + +--------=_MB5D12DEC9-3C13-4205-A6C8-2772BB5E8F57 +Content-Type: text/plain; charset=utf-8; format=flowed +Content-Transfer-Encoding: quoted-printable + +This is a test email that shouldn't be displayed when filtered for the=20 +"important" word in the subject. +--------=_MB5D12DEC9-3C13-4205-A6C8-2772BB5E8F57 +Content-Type: text/html; charset=utf-8 +Content-Transfer-Encoding: quoted-printable + + + + + +This is a test email that shouldn't be displayed when filtered for th= +e "important" word in the subject. +--------=_MB5D12DEC9-3C13-4205-A6C8-2772BB5E8F57-- diff --git a/Lombiq.EmailClient.sln b/Lombiq.EmailClient.sln new file mode 100644 index 0000000..0faa812 --- /dev/null +++ b/Lombiq.EmailClient.sln @@ -0,0 +1,28 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Lombiq.EmailClient", "Lombiq.EmailClient\Lombiq.EmailClient.csproj", "{6CAE54CF-E3C9-4AD0-B40B-6719E1B7BA21}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Lombiq.EmailClient.Samples", "Lombiq.EmailClient.Samples\Lombiq.EmailClient.Samples.csproj", "{E052E1C6-CE00-4078-91F9-929D6129575B}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Lombiq.EmailClient.Tests.UI", "Lombiq.EmailClient.Tests.UI\Lombiq.EmailClient.Tests.UI.csproj", "{EBB4C673-FD0D-4FD6-BDDB-93AC3A2DE3C1}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Release|Any CPU = Release|Any CPU + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {6CAE54CF-E3C9-4AD0-B40B-6719E1B7BA21}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {6CAE54CF-E3C9-4AD0-B40B-6719E1B7BA21}.Debug|Any CPU.Build.0 = Debug|Any CPU + {6CAE54CF-E3C9-4AD0-B40B-6719E1B7BA21}.Release|Any CPU.ActiveCfg = Release|Any CPU + {6CAE54CF-E3C9-4AD0-B40B-6719E1B7BA21}.Release|Any CPU.Build.0 = Release|Any CPU + {E052E1C6-CE00-4078-91F9-929D6129575B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {E052E1C6-CE00-4078-91F9-929D6129575B}.Debug|Any CPU.Build.0 = Debug|Any CPU + {E052E1C6-CE00-4078-91F9-929D6129575B}.Release|Any CPU.ActiveCfg = Release|Any CPU + {E052E1C6-CE00-4078-91F9-929D6129575B}.Release|Any CPU.Build.0 = Release|Any CPU + {EBB4C673-FD0D-4FD6-BDDB-93AC3A2DE3C1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {EBB4C673-FD0D-4FD6-BDDB-93AC3A2DE3C1}.Debug|Any CPU.Build.0 = Debug|Any CPU + {EBB4C673-FD0D-4FD6-BDDB-93AC3A2DE3C1}.Release|Any CPU.ActiveCfg = Release|Any CPU + {EBB4C673-FD0D-4FD6-BDDB-93AC3A2DE3C1}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection +EndGlobal diff --git a/Readme.md b/Readme.md index 604984e..1b30a97 100644 --- a/Readme.md +++ b/Readme.md @@ -2,13 +2,46 @@ ## About -Add a general overview of the project here. Keep or remove the OSOCE note below as necessary. +An email client for Orchard Core that can fetch emails (including attachments) from a server. Right now it supports IMAP only. There's also a feature that can sync emails periodically from a background task in an extensible way; you can create your content items from emails for example. Do you want to quickly try out this project and see it in action? Check it out in our [Open-Source Orchard Core Extensions](https://github.com/Lombiq/Open-Source-Orchard-Core-Extensions) full Orchard Core solution and also see our other useful Orchard Core-related open-source projects! ## Documentation -Add detailed documentation here. +For detailed, documented examples, check out the [samples project](Lombiq.EmailClient.Samples). + +### Fetching emails from an IMAP server + +To fetch emails from an IMAP server, enable the `Lombiq.EmailClient.Imap` feature. Then you can configure the IMAP server settings in the admin dashboard under Configuration -> Settings -> IMAP. You can also configure the IMAP settings in the `appsettings.json` file: + +```json +{ + "Lombiq_EmailClient_Imap": { + "Host": "imap.example.com", + "Port": 993, + "UseSsl": true, + "RequireAuthentication": true, + "Username": "username", + "Password": "password" + } +} +``` + +Then, inject the `IEmailClient` service and use it to fetch emails or process attachments. It's also possible to parameterize the email fetching process by using the `EmailFilterParameters` class; you can filter emails by subject for example. + +### Syncing emails periodically + +To sync emails periodically, enable the `Lombiq.EmailClient.EmailSync` feature. Then you can configure the sync settings in the admin dashboard under Configuration -> Settings -> Email Sync. You can also configure the sync settings in the `appsettings.json` file: + +```json +{ + "Lombiq_EmailClient_EmailSync": { + "SubjectFilter": "important" + } +} +``` + +The email syncing is happening automatically in the `EmailSyncBackgroundTask` once per day by default. You can also trigger the sync manually by using the `IEmailSyncService` service. Check out the sample project for more details. ## Contributing and support