Net4x.EmailLibrary 1.3.0.26248

Net4x.EmailLibrary

Configuration-driven SMTP email sending for .NET. You supply a subject, a body and attachments; the server, port, credentials, sender, recipients, SSL and the send/dry-run switch all come from your application's configuration.

Targets net35, net40, net45 and netstandard2.0.

Install

dotnet add package Net4x.EmailLibrary

or, on legacy projects:

Install-Package Net4x.EmailLibrary

Quick start

using EmailLibrary.Mail;

// plain-text body
EmailHelper.Instance.SendEmails("Nightly report", "All jobs completed.");

// HTML body with attachments
EmailHelper.Instance.SendEmails(
    "Invoice 2024/117",
    "<p>Please find the invoice attached.</p>",
    isHtmlBody: true,
    attachments: new[] { @"C:\out\invoice-117.pdf" });

Both overloads return a System.Net.Mail.MailMessage, but do not read the return value as a delivery result: it reports whether a copy of the message was filed in the MessageDump directory, not whether the message went out. With no MessageDump configured a successful send returns null; with one configured, a send that failed still returns the message. Use logging, not the return value, to confirm delivery.

public interface IEmailHelper
{
    MailMessage SendEmails(string title, string body, params string[] attachments);
    MailMessage SendEmails(string title, string body, bool isHtmlBody, params string[] attachments);
}

Configuration

Settings are read through Net4x.Configuration.Library's ArgumentGetter, so they can come from appSettings in App.config/Web.config, a JSON configuration file, environment variables or the command line — whichever sources the host application has set up. Values are read on every send, never cached, so changing configuration at runtime takes effect immediately.

Example App.config:

<configuration>
  <appSettings>
    <add key="SmtpServer" value="smtp.example.com" />
    <add key="SmtpPort" value="587" />
    <add key="UseSsl" value="true" />
    <add key="SmtpUserName" value="noreply@example.com" />
    <add key="SmtpPassword" value="..." />
    <add key="FromEmail" value="noreply@example.com" />
    <add key="ToEmail" value="ops@example.com|audit@example.com" />
    <add key="CcEmail" value="" />
    <add key="SendEmails" value="true" />
  </appSettings>
</configuration>

ToEmail and CcEmail are split into multiple addresses using ArgumentGetter.Instance.Separator (| by default); set that property to match the delimiter you use.

A value that contains no separator is not treated as a one-element list - it is parsed as JSON instead. So a single recipient must be written as a JSON array, or the setting resolves to no recipients at all:

<add key="ToEmail" value="ops@example.com|audit@example.com" />


<add key="ToEmail" value='["ops@example.com"]' />

CC recipients are delivered, but the current SMTP layer places them on the To header rather than a Cc header.

Dry runs

Leaving SendEmails set to false is the intended way to exercise an integration without delivering mail. The subject, sender, recipients, CC list and every attachment path are still written to the log — only the SMTP call is skipped.

Renaming the configuration keys

If your application already stores these settings under different names, do not rename your configuration: supply your own key names and build the configuration accessor yourself.

using EmailLibrary.Interfaces.Model;
using EmailLibrary.Model;

IMailConfigurationConstants keys = new MailConfigurationConstants
{
    SmtpServer = "Mail:Host",
    SmtpPort   = "Mail:Port",
    FromEmail  = "Mail:Sender",
    ToEmail    = "Mail:Recipients",
    SendEmails = "Mail:Enabled",
};

IMailConfigurationVariables mail = MailConfigurationVariables.CreateInstance(keys);

int port = mail.SmtpPort;                      // typed read, defaults to 25
mail.ToEmail = new[] { "a@b.com", "c@d.com" }; // typed write, persisted through ArgumentGetter

IMailConfigurationVariables exposes every setting as a typed, read/write property (string, int, bool, string[]), which also makes it a convenient way to inspect or adjust mail configuration from code.

Logging and error handling

The library logs through CoreLibrary.Logging.LoggerFactory, using whichever logger the host application has registered. Each call logs a one-line summary — [subject] email from: … to: … cc: … — followed by the attachment list. Messages are localized; English and Italian (it-IT) are included.

How a delivery failure surfaces depends on whether a MessageDump directory is configured:

• Without MessageDump an SmtpException propagates to the caller.
• With MessageDump nothing is thrown; the failure is recorded as a .txt note beside the saved copy of the message, and logged.

Set MessageDump to a writable directory if you would rather handle failures from your logs than from exceptions.

Dependencies

• Net4x.Configuration.Library — configuration access
• Net4x.DataAccessLibrary.Web — SMTP delivery
• Net4x.DataAccessLibrary.Data.Work

Copyright: Copyright (c) Piero Viano. All rights reserved. Authors: Piero Viano Company: Piero Viano