GPALMail.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using GenerallyPositive;
 
namespace GenerallyPositive
{
    using System.Collections.Generic;
    using System.IO;
    using MailKit.Net.Imap;
    using MailKit.Net.Pop3;
    using MailKit;
    using MailKit.Net.Smtp;
    using MailKit.Search;
    using MimeKit;

    public class GPALMail : IGPALMail
    {
        private GPALMailSettings gPALMailSettings;
        private static string MailSettingsFilePath { get; set; } = "./GPALMail.yaml";
        private GPALMailSettings GPALMailSettings
        {
            get
            {
                return gPALMailSettings;
            }
            set
            {
                gPALMailSettings = value;
            }
        }
        internal GPALMail()
        {
            GPALMailSettings = new GPALMailSettings();
            GPALMailSettings.ToEmailAddresses = new List<MailboxAddress>();
            GPALMailSettings.CcEmailAddresses = new List<MailboxAddress>();
            GPALMailSettings.BccEmailAddresses = new List<MailboxAddress>();
            GPALMailSettings.Attachments = new List<string>();
            GPALMailSettings.ReceivedEmails = new List<ReceivedEmail>();
            LoadSettings();
        }
        public IGPALMail ToGPALObject()
        {
            return this;
        }

        public IAllowEmailServerSettingsAndName WithIMAPServerName(string serverName)
        {
            GPALMailSettings.IMAPServerName = serverName;
            GPALMailSettings.POPServerName = null;
            return this;
        }

        public IAllowEmailServerSettingsAndName WithPOPServerName(string serverName)
        {
            GPALMailSettings.POPServerName = serverName;
            GPALMailSettings.IMAPServerName = null;
            return this;
        }

        public IAllowEmailServerSettingsAndName WithSMTPServerName(string serverName)
        {
            GPALMailSettings.SMTPServerName = serverName;
            return this;
        }

        public IAllowEmailServerSettingsAndName WithIMAPPortNum(int portNum = 993)
        {
            GPALMailSettings.IMAPPortNum = portNum;
            return this;
        }

        public IAllowEmailServerSettingsAndName WithPOPPortNum(int portNum = 110)
        {
            GPALMailSettings.POPPortNum = portNum;
            return this;
        }

        public IAllowEmailServerSettingsAndName WithSMTPPortNum(int portNum = 465)
        {
            GPALMailSettings.SMTPPortNum = portNum;
            return this;
        }

        public IAllowEmailServerSettingsAndName WithCredentials(ICredentials credentials)
        {
            GPALMailSettings.Credentials = credentials;
            return this;
        }
 
        // what a settings file holds, readable so a form can show it. everything else about a message is the
        // envelope, and the login is the credential's business
        public string SMTPServerName => GPALMailSettings.SMTPServerName;
        public int SMTPPortNum => GPALMailSettings.SMTPPortNum;
        public string IMAPServerName => GPALMailSettings.IMAPServerName;
        public int IMAPPortNum => GPALMailSettings.IMAPPortNum;
        public string POPServerName => GPALMailSettings.POPServerName;
        public int POPPortNum => GPALMailSettings.POPPortNum;
        public string FromAddress => GPALMailSettings.FromAddress;
 
        // the credential if there is one, otherwise whatever was set by hand
        private string ResolvedUserName
        {
            get
            {
                return null != GPALMailSettings.Credentials ? ((Credentials)GPALMailSettings.Credentials).Username : GPALMailSettings.UserName;
            }
        }
 
        private string ResolvedPassword
        {
            get
            {
                return null != GPALMailSettings.Credentials ? ((Credentials)GPALMailSettings.Credentials).Password : GPALMailSettings.Password;
            }
        }

        public IAllowEmailServerSettingsAndName WithUserName(string userName)
        {
            GPALMailSettings.UserName = userName;
            return this;
        }

        public IAllowEmailServerSettingsAndName WithPassword(string password)
        {
            GPALMailSettings.Password = password;
            return this;
        }

        // whichever address was added last, so .WithName knows which one it is naming
        private MailboxAddress lastAddress = null;
 
        public IAllowNameEnvelopeAndActions WithFromEmailAddress(string mailAddress)
        {
            GPALMailSettings.FromEmailAddress = MailboxAddress.Parse(mailAddress);
            lastAddress = GPALMailSettings.FromEmailAddress;
            return this;
        }
        public IAllowNameEnvelopeAndActions WithToEmailAddress(string mailAddress)
        {
            foreach (MailboxAddress mailboxAddress in ParseEmailAddresses(mailAddress))
            {
                GPALMailSettings.ToEmailAddresses.Add(mailboxAddress);
                lastAddress = mailboxAddress;
            }
            return this;
        }

        public IAllowNameEnvelopeAndActions WithCcEmailAddress(string mailAddress)
        {
            foreach (MailboxAddress mailboxAddress in ParseEmailAddresses(mailAddress))
            {
                GPALMailSettings.CcEmailAddresses.Add(mailboxAddress);
                lastAddress = mailboxAddress;
            }
            return this;
        }

        public IAllowNameEnvelopeAndActions WithBccEmailAddress(string mailAddress)
        {
            foreach (MailboxAddress mailboxAddress in ParseEmailAddresses(mailAddress))
            {
                GPALMailSettings.BccEmailAddresses.Add(mailboxAddress);
                lastAddress = mailboxAddress;
            }
            return this;
        }

        public IAllowNameEnvelopeAndActions WithToEmailAddress(string[] emailParts)
        {
            foreach (MailboxAddress mailboxAddress in CreateEmailAddresses(emailParts))
            {
                GPALMailSettings.ToEmailAddresses.Add(mailboxAddress);
                lastAddress = mailboxAddress;
            }
            return this;
        }

        public IAllowNameEnvelopeAndActions WithCcEmailAddress(string[] emailParts)
        {
            foreach (MailboxAddress mailboxAddress in CreateEmailAddresses(emailParts))
            {
                GPALMailSettings.CcEmailAddresses.Add(mailboxAddress);
                lastAddress = mailboxAddress;
            }
            return this;
        }

        public IAllowNameEnvelopeAndActions WithBccEmailAddress(string[] emailParts)
        {
            foreach (MailboxAddress mailboxAddress in CreateEmailAddresses(emailParts))
            {
                GPALMailSettings.BccEmailAddresses.Add(mailboxAddress);
                lastAddress = mailboxAddress;
            }
            return this;
        }

        public IAllowEmailEnvelopeAndActions WithAttachment(GPALFile attachmentFile)
        {
            foreach (string filename in attachmentFile.Filenames)
                try
                {
                    string directory = Path.GetDirectoryName(filename);
                    string filenamepart = Path.GetFileName(filename);
                    string[] matches = Directory.GetFiles(false == string.IsNullOrEmpty(directory) ? directory : @".\", filenamepart);
 
                    // said out loud, because a name that matches no file attaches nothing and the message still sends
                    if (0 == matches.Length)
                        GPAL.PublishSimpleEvent(Enums.GPALEventType.WARNING, $"Nothing to attach at [{filename}]", attachmentFile, Enums.GPALObjectType.Other);
 
                    foreach (string filename2 in matches)
                        try 
                        { 
                            GPALMailSettings.Attachments.Add(filename2);
                        }
                        catch (Exception ex)
                        {
                            GPAL.PublishSimpleEvent(Enums.GPALEventType.EXCEPTION, $"Unable to add file attachments [{filename2}].", attachmentFile, Enums.GPALObjectType.Other, ex);
                        }
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(Enums.GPALEventType.EXCEPTION, $"Unable to add file attachments [{attachmentFile.Filename}].", attachmentFile, Enums.GPALObjectType.Other, ex);
                }
            return this;
        }

        public IAllowEmailEnvelopeAndActions WithBody(string body)
        {
            if (true == IsHtml(body))
                GPALMailSettings.BodyHTML = body;
            else
                GPALMailSettings.BodyText = body;
            return this;
        }

        public IAllowEmailEnvelopeAndActions WithSubject(string subject)
        {
            GPALMailSettings.Subject = subject;
            return this;
        }

        public IAllowEmailEnvelopeAndActions WithName(string name)
        {
            // the address this follows, whether that was the from, a to, a cc or a bcc. named after the fact
            // rather than parsed out of the address, so "Dead Mike <mike@x.com>" is not the only way to say it
            if (null == lastAddress)
                GPAL.PublishSimpleEvent(Enums.GPALEventType.WARNING, $"No address to put the name [{name}] on. Name an address after adding it", this, Enums.GPALObjectType.Other);
            else
                lastAddress.Name = name;
 
            return this;
        }

        public IAllowEmailEnvelopeAndActions Send()
        {
            if (null == GPALMailSettings.FromEmailAddress)
            {
                // said here rather than thrown from inside MimeKit as a null argument called "address"
                GPAL.PublishSimpleEvent(Enums.GPALEventType.ERROR, $"No from address to send with", this, Enums.GPALObjectType.Other);
 
                return this;
            }
 
            var message = new MimeMessage();
            message.From.Add(GPALMailSettings.FromEmailAddress);
 
            if (null != GPALMailSettings.ToEmailAddresses && 0 < GPALMailSettings.ToEmailAddresses.Count)
                foreach (var to in GPALMailSettings.ToEmailAddresses)
                    message.To.Add(to);
 
            if (null != GPALMailSettings.CcEmailAddresses && 0 < GPALMailSettings.CcEmailAddresses.Count)
                foreach (var cc in GPALMailSettings.CcEmailAddresses)
                    message.Cc.Add(cc);
 
            if (null != GPALMailSettings.BccEmailAddresses && 0 < GPALMailSettings.BccEmailAddresses.Count)
                foreach (var bcc in GPALMailSettings.BccEmailAddresses)
                    message.Bcc.Add(bcc);
 
            message.Subject = GPALMailSettings.Subject;
            var bodyBuilder = new BodyBuilder();
            if (null != GPALMailSettings.BodyHTML)
                bodyBuilder.HtmlBody = GPALMailSettings.BodyHTML;
            else
                bodyBuilder.TextBody = GPALMailSettings.BodyText;
            if (null != GPALMailSettings.Attachments && 0 < GPALMailSettings.Attachments.Count)
            {
                foreach (var attachment in GPALMailSettings.Attachments)
                {
                    bodyBuilder.Attachments.Add(attachment);
                }
            }
            message.Body = bodyBuilder.ToMessageBody();
 
            using (var client = new SmtpClient())
            {
                try
                {
                    client.Connect(GPALMailSettings.SMTPServerName, GPALMailSettings.SMTPPortNum, false);
                }
                catch   // a cert exception most probably
                {
                    client.ServerCertificateValidationCallback = (s, c, h, e) => true;  // Bad, but protects against bad certs we can check, or something.
                    client.DeliveryStatusNotificationType = MailKit.Net.Smtp.DeliveryStatusNotificationType.Full;
                    client.SslProtocols = System.Security.Authentication.SslProtocols.Tls11 | System.Security.Authentication.SslProtocols.Tls12;
 
                    client.Connect(GPALMailSettings.SMTPServerName, GPALMailSettings.SMTPPortNum, false);
                }
                // a server that wants to know who is sending. nothing to authenticate with means nothing to do,
                // which is how an open relay on a local port has always worked here
                if (false == string.IsNullOrEmpty(ResolvedUserName))
                    client.Authenticate(ResolvedUserName, ResolvedPassword);
 
                client.Send(message);
                client.Disconnect(true);
            }
 
            return this;
        }

        public IAllowEmailEnvelopeAndActions Receive()
        {
            // whichever was configured. a pop server named means pop, because naming one and having it ignored
            // is worse than either
            if (false == string.IsNullOrWhiteSpace(GPALMailSettings.POPServerName))
                ReceiveOverPOP();
            else if (false == string.IsNullOrWhiteSpace(GPALMailSettings.IMAPServerName))
                ReceiveOverIMAP();
            else
                GPAL.PublishSimpleEvent(Enums.GPALEventType.ERROR, $"No pop or imap server to read mail from", this, Enums.GPALObjectType.Other);
 
            return this;
        }

        public IAllowEmailEnvelopeAndActions Receive(out List<ReceivedEmail> receivedEmails)
        {
            Receive();
 
            receivedEmails = new List<ReceivedEmail>(GPALMailSettings.ReceivedEmails);
 
            GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"Handing back [{receivedEmails.Count}] received emails.", this, Enums.GPALObjectType.Other);
 
            return this;
        }

        public IAllowEmailEnvelopeAndActions WithUnreadOnly(bool unreadOnly)
        {
            GPALMailSettings.UnreadOnly = unreadOnly;
            return this;
        }

        public IAllowEmailEnvelopeAndActions WithMaxMessages(int maxMessages)
        {
            GPALMailSettings.MaxMessages = maxMessages;
            return this;
        }
 
        private void ReceiveOverPOP()
        {
            using (var client = new Pop3Client())
            {
                client.Connect(GPALMailSettings.POPServerName, GPALMailSettings.POPPortNum, MailKit.Security.SecureSocketOptions.Auto);
                client.Authenticate(ResolvedUserName, ResolvedPassword);
 
                // pop has no notion of a read message, so unread-only cannot be honoured here
                if (true == GPALMailSettings.UnreadOnly)
                    GPAL.PublishSimpleEvent(Enums.GPALEventType.WARNING, $"POP cannot tell read from unread, so every message is being fetched from [{GPALMailSettings.POPServerName}]", this, Enums.GPALObjectType.Other);
 
                int first = Math.Max(0, client.Count - GPALMailSettings.MaxMessages);
 
                for (int i = first; i < client.Count; i++)
                    Collect(client.GetMessage(i), null);
 
                client.Disconnect(true);
            }
        }
 
        private void ReceiveOverIMAP()
        {
            using (var client = new ImapClient())
            {
                client.Connect(GPALMailSettings.IMAPServerName, GPALMailSettings.IMAPPortNum, true);
                client.Authenticate(ResolvedUserName, ResolvedPassword);
 
                var inbox = client.Inbox;
                inbox.Open(MailKit.FolderAccess.ReadOnly);
 
                // ask the server which messages qualify rather than dragging the mailbox down to find out
                IList<UniqueId> ids = inbox.Search(true == GPALMailSettings.UnreadOnly
                    ? SearchQuery.NotSeen
                    : SearchQuery.All);
 
                int first = Math.Max(0, ids.Count - GPALMailSettings.MaxMessages);
 
                for (int i = first; i < ids.Count; i++)
                    Collect(inbox.GetMessage(ids[i]), ids[i]);
 
                client.Disconnect(true);
            }
        }

        public IAllowEmailEnvelopeAndActions MarkAllAsRead()
        {
            ApplyFlag(GPALMailSettings.ReceivedEmails, MessageFlags.Seen, false);
            return this;
        }

        public IAllowEmailEnvelopeAndActions DeleteAll()
        {
            ApplyFlag(GPALMailSettings.ReceivedEmails, MessageFlags.Deleted, true);
            return this;
        }

        internal void ApplyFlag(IEnumerable<ReceivedEmail> messages, MessageFlags flag, bool expunge)
        {
            List<UniqueId> uids = messages.Where(m => null != m?.Uid).Select(m => m.Uid.Value).ToList();
 
            if (0 == uids.Count)
                GPAL.PublishSimpleEvent(Enums.GPALEventType.WARNING, $"Nothing to flag: no message came from an IMAP Receive", this, Enums.GPALObjectType.Other);
            else
                using (var client = new ImapClient())
                {
                    client.Connect(GPALMailSettings.IMAPServerName, GPALMailSettings.IMAPPortNum, true);
                    client.Authenticate(ResolvedUserName, ResolvedPassword);
 
                    var inbox = client.Inbox;
                    inbox.Open(MailKit.FolderAccess.ReadWrite);
                    inbox.AddFlags(uids, flag, true);
 
                    if (true == expunge)
                        inbox.Expunge(uids);
 
                    client.Disconnect(true);
 
                    GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"Flagged [{uids.Count}] message(s) as [{flag}].", this, Enums.GPALObjectType.Other);
                }
        }
 
        private void Collect(MimeMessage message, UniqueId? uid)
        {
            ReceivedEmail received = new ReceivedEmail
            {
                Subject = message.Subject,
                From = message.From.ToString(),
                // transactional mail is often html with no text part at all, and an empty body is no use
                Body = message.TextBody ?? message.HtmlBody,
                HtmlBody = message.HtmlBody,
                Received = message.Date.LocalDateTime,
                MessageId = message.MessageId,
                Uid = uid,
                Mailbox = this
            };
 
            // the name each attachment arrived under, and the part itself, so the file can be written later
            // by whoever wants it and nothing is written by the act of reading mail
            foreach (MimeEntity attachment in message.Attachments)
            {
                received.Attachments.Add(attachment.ContentDisposition?.FileName ?? attachment.ContentType?.Name);
                received.AttachmentParts.Add(attachment);
            }
 
            GPALMailSettings.ReceivedEmails.Add(received);
        }
        public IAllowEmailEnvelopeAndActions SaveTo(GPALFile directory)
        {
            int written = 0;
 
            foreach (ReceivedEmail received in GPALMailSettings.ReceivedEmails)
                written += received.SaveTo(directory).Count;
 
            GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"Wrote [{written}] attachments to [{directory.Filename}].", this, Enums.GPALObjectType.Other);
 
            return this;
        }

        public IAllowEmailEnvelopeAndActions Clear()
        {
            // the from address stays: it is who you send as, it is saved with the server settings, and every
            // message after this one would have to say it again
            GPALMailSettings.ToEmailAddresses.Clear();
            GPALMailSettings.CcEmailAddresses.Clear();
            GPALMailSettings.BccEmailAddresses.Clear();
            GPALMailSettings.Subject = null;
            GPALMailSettings.BodyText = null;
            GPALMailSettings.Attachments.Clear();
            GPALMailSettings.ReceivedEmails.Clear();
            return this;
        }

        public IAllowEmailEnvelopeAndActions LoadSettings(GPALFile mailSettingsFile = null)
        {
            if (mailSettingsFile != null) 
                MailSettingsFilePath = mailSettingsFile.Filename;
 
            if (true == System.IO.File.Exists(MailSettingsFilePath))
                GPAL.Converter.WithInput((GPALFile)MailSettingsFilePath).SaveTo(ref gPALMailSettings);
            else
                // nothing to load, so leave a file with the settings in it to fill in. a workflow that sets them
                // itself and saves overwrites this with the real thing
                SaveSettings();
 
            return this;
        }

        public IAllowEmailEnvelopeAndActions SaveSettings(GPALFile mailSettingsFile = null)
        {
            if (mailSettingsFile != null) MailSettingsFilePath = mailSettingsFile.Filenames[0];
            GPAL.Converter.WithInput(gPALMailSettings).SaveTo((GPALFile)MailSettingsFilePath);
            return this;
        }
        #region HELPERS
        public static List<MailboxAddress> ParseEmailAddresses(string input)
        {
 
            // Split the input string based on delimiters
            string[] emailParts = input.Split(new char[] { ',', ';', '|' });
            return CreateEmailAddresses(emailParts);
        }

        internal static List<MailboxAddress> CreateEmailAddresses(string[] emailParts)
        {
            List<MailboxAddress> addresses = new List<MailboxAddress>();
            foreach (string emailPart in emailParts)
            {
                string email = emailPart.Trim();
                if (!string.IsNullOrEmpty(email))
                {
                    // Create a MailboxAddress object
                    MailboxAddress address = MailboxAddress.Parse(email);
                    addresses.Add(address);
                }
            }
            return addresses;
        }
        static bool IsHtml(string text)
        {
            // 
            // Check if the text starts with an XML declaration
            if (text.TrimStart().StartsWith("<!DOCTYPE html>", StringComparison.OrdinalIgnoreCase))
                return true;
            else if (text.TrimStart().StartsWith("<?xml", StringComparison.OrdinalIgnoreCase))
                return false;
 
            // Define a regular expression pattern to match HTML tags
            string pattern = @"<\s*([^ >]+)[^>]*>.*?<\s*/\s*\1\s*>";
 
            // Use Regex to search for HTML tags in the text
            return System.Text.RegularExpressions.Regex.IsMatch(text, pattern);
        }
 
        #endregion HELPERS
    }

    public class ReceivedEmail
    {
        public string Subject { get; set; }
        public string From { get; set; }
        public string Body { get; set; }
        public string HtmlBody { get; set; }
        public DateTime Received { get; set; }
        public string MessageId { get; set; }
 
        // the imap identity of the message, so MarkAsRead knows which one to flag. null over pop
        internal UniqueId? Uid { get; set; }
 
        // the mail object that read this message, which is who still holds the server and the login
        internal GPALMail Mailbox { get; set; }

        public ReceivedEmail MarkAsRead()
        {
            Mailbox.ApplyFlag(new[] { this }, MessageFlags.Seen, false);
            return this;
        }

        public ReceivedEmail Delete()
        {
            Mailbox.ApplyFlag(new[] { this }, MessageFlags.Deleted, true);
            return this;
        }

        public List<string> Attachments { get; set; } = new List<string>();
 
        // the attachments themselves, held until someone asks for them on disk
        internal List<MimeEntity> AttachmentParts { get; set; } = new List<MimeEntity>();

        public List<GPALFile> SaveTo(GPALFile directory)
        {
            List<GPALFile> retVal = new List<GPALFile>();
 
            if (0 < AttachmentParts.Count)
                Directory.CreateDirectory(directory.Filename);
 
            foreach (MimeEntity attachment in AttachmentParts)
            {
                // the name the sender chose, taken apart so nothing but a filename is used and a name like
                // ..\..\startup.cmd cannot write outside the directory that was asked for
                string filename = Path.GetFileName(attachment.ContentDisposition?.FileName ?? attachment.ContentType?.Name);
                string path = Path.Combine(directory.Filename, filename);
 
                using (FileStream stream = File.Create(path))
                    if (attachment is MimePart part)
                        part.Content.DecodeTo(stream);
                    else
                        attachment.WriteTo(stream);
 
                retVal.Add(path);
            }
 
            return retVal;
        }
    }
}