Easy.Notifications 1.2.0

.NET 6.0 .NET Standard 2.1 .NET Framework 4.7

dotnet add package Easy.Notifications --version 1.2.0

NuGet\Install-Package Easy.Notifications -Version 1.2.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Easy.Notifications" Version="1.2.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Easy.Notifications" Version="1.2.0" />
                    

                            Directory.Packages.props

<PackageReference Include="Easy.Notifications" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Easy.Notifications --version 1.2.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Easy.Notifications, 1.2.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Easy.Notifications@1.2.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Easy.Notifications&version=1.2.0
                    

                            Install as a Cake Addin

#tool nuget:?package=Easy.Notifications&version=1.2.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Easy.Notifications

Easy.Notifications is a robust, high-performance, and channel-agnostic notification engine for .NET 6+.

It is designed for enterprise applications that require Reliable Dispatching without blocking the main execution thread. It combines System.Threading.Channels, Priority Queues, and Hybrid Persistence to ensure your messages (Email, SMS, Chat) are delivered safely, even under heavy load.

Features

Fire-and-Forget Architecture: Uses in-memory channels to offload sending logic instantly, ensuring zero-latency for the producer.
Priority Queues: Process Urgent messages (e.g., OTPs, Alerts) immediately, bypassing Normal or Low priority marketing queues.
Resilience & Retries: Automatic retry mechanism with exponential backoff for failed providers (requires Persistence package).
Hybrid Cancellation: Cancel millions of pending campaign messages instantly using a smart Memory + DB hybrid lock mechanism.
Live Monitoring: Real-time hooks for SignalR to watch notification traffic (Success/Fail) as it happens.
Audit Logging: (Optional) Persist every attempt, success, and failure to SQL Server using the EntityFramework package.
Built-in Templating: Lightweight template engine for dynamic content replacement (e.g., Hello {{Name}}).
Modular Architecture: Designed with Dependency Injection in mind; add only the providers you need.
Multi-Channel Support:
- Email: SMTP, SendGrid, Mailgun.
- SMS/WhatsApp: Twilio, Vonage.
- Chat: Slack (Block Kit), Microsoft Teams (Message Cards), Telegram.
- Realtime: SignalR (WebSockets).
Rich Content Support:
- Automatically converts messages to Slack Block Kit structures.
- Renders Microsoft Teams Message Cards with custom colors and sections via Metadata.

Architecture

The library separates the Dispatching logic from the Processing logic to ensure maximum throughput.

Producer: Your Application (API/Service) calls INotificationService.SendAsync().
Dispatcher: The payload is instantly written to the appropriate Priority Channel (Memory). Control returns to your code in microseconds.
Worker: A background service (BackgroundNotificationWorker) consumes messages, strictly processing Urgent items before Normal ones.
Provider: The specific provider (e.g., SlackProvider, SmtpEmailProvider) executes the external API call. Failures are handled by the Retry Mechanism.

Installation

Install via NuGet Package Manager:

Install-Package Easy.Notifications

Or via .NET CLI:

dotnet add package Easy.Notifications

(Optional) If you need database logging and retry persistence:

dotnet add package Easy.Notifications.Persistence.EntityFramework

Configuration

1. Register Services (Program.cs)

Use the fluent API to configure exactly what you need.

using Easy.Notifications.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 1. Add Core Services (Dispatcher, Worker)
builder.Services.AddEasyNotifications();

// 2. Add Desired Providers (Modular Registration)
// Email
builder.Services.AddSmtpEmail(builder.Configuration);
// builder.Services.AddSendGrid(builder.Configuration);
// builder.Services.AddMailgun(builder.Configuration);

// 3. SMS & WhatsApp
builder.Services.AddTwilio(builder.Configuration);
// builder.Services.AddVonage(builder.Configuration);

// 4. Chat Apps (Slack, Teams, Telegram)
builder.Services.AddChatProviders(builder.Configuration);

// 5. (Optional) Add Persistence for Logs & Retries
var connString = builder.Configuration.GetConnectionString("NotificationDb");
builder.Services.AddNotificationPersistence(options => options.UseSqlServer(connString));

// 6. Realtime
builder.Services.AddSignalRNotifications();

// 7. (Optional) Add Real-Time Monitoring
builder.Services.AddSingleton<INotificationLiveMonitor, SignalRNotificationMonitor>();

var app = builder.Build();

// Map SignalR Hub (If using Realtime)
app.MapHub<NotificationHub>("/notifications");

app.Run();

2. Configure Settings (appsettings.json)

{
  "NotificationConfiguration": {
    "RetryConfiguration": {
      "MaxRetryCount": 5,
      "IntervalInMinutes": 10
    },
    "EmailConfiguration": {
      "Host": "smtp.example.com",
      "Port": 587,
      "Username": "apikey",
      "Password": "secret-password",
      "Sender": "no-reply@example.com",
      "SenderDisplayName": "System Alerts",
      "EnableSsl": true
    },
    "TwilioConfiguration": {
      "AccountSid": "ACxxxxxxxx...",
      "AuthToken": "xxxxxxxx...",
      "FromNumber": "+15551234567"
    },
    "SendGridConfiguration": {
      "ApiKey": "SG.xxxxxxxx...",
      "SenderEmail": "alert@example.com",
      "SenderName": "Alert Bot"
    },
    "VonageConfiguration": {
      "ApiKey": "a1b2c3d4",
      "ApiSecret": "xxxxxxxxxxxx",
      "Sender": "MyBrand",
      "FromNumber": "MyBrand"
    },
    "MailgunConfiguration": {
      "ApiKey": "<MAILGUN_API_KEY>",
      "Domain": "<MAILGUN_DOMAIN>",
      "SenderEmail": "noreply@example.com",
      "SenderName": "Easy Notifications"
    },
    "TelegramConfiguration": {
      "BotToken": "123456:ABC-DEF..."
    }
  }
}

Usage

Inject INotificationService into your controllers.

1. Sending an Urgent Alert (Priority Queue)

Urgent messages jump to the front of the line.

[HttpPost("send-otp")]
public async Task<IActionResult> SendOtp()
{
    var payload = new NotificationPayload
    {
        Subject = "Login Code",
        Body = "Your code is: **123456**",
        Priority = NotificationPriority.Urgent, // Processed immediately
        Recipients = new List<Recipient> 
        { 
            Recipient.Sms("+15550001234"),
            Recipient.WhatsApp("+15550001234")
        }
    };

    await _notifier.SendAsync(payload);
    return Ok();
}

2. Sending Rich Chat Messages (Context Aware)

Send styled messages to Slack and Teams using the same payload.

var payload = new NotificationPayload
{
    Subject = "⚠️ Server High Load",
    Body = "Server **PROD-01** is at 99% CPU.",
    Metadata = new Dictionary<string, object>
    {
        { "ThemeColor", "FF0000" }, // Red card for Teams
        { "Server", "Prod-01" },    // Field for Slack
        { "Region", "US-East" }
    },
    Recipients = new List<Recipient>
    {
        Recipient.Teams("https://outlook.office.com/webhook/..."),
        Recipient.Slack("https://hooks.slack.com/services/...")
    }
};

await _notifier.SendAsync(payload);

3. Campaign Management (Grouping & Cancellation)

You can group notifications (e.g., a newsletter) and cancel them instantly if you realize there is a typo.

Sending:

var payload = new NotificationPayload
{
    GroupId = "Newsletter-Feb-2026", // Link messages to a group
    Subject = "Monthly Update",
    Recipients = // list of 10,000 users...
};
await _notifier.SendAsync(payload);

Cancelling:

public class AdminController : ControllerBase
{
    private readonly INotificationCancellationManager _cancellationManager;

    [HttpPost("cancel-campaign")]
    public async Task<IActionResult> Cancel(string campaignId)
    {
        // Instantly stops processing this group in memory and DB
        await _cancellationManager.CancelGroupAsync(campaignId, TimeSpan.FromHours(24));
        return Ok("Campaign stopped.");
    }
}

4. Multi-Channel Broadcast (Email + SMS)

var payload = new NotificationPayload
{
    Subject = "Welcome {{Name}}",
    Body = "Hi {{Name}}, your account is activated.",
    TemplateData = new Dictionary<string, string> { { "Name", "John Doe" } },
    
    Recipients = new List<Recipient>
    {
        Recipient.Email("john@example.com", "John Doe"),
        Recipient.Sms("+15550001234"),
        Recipient.WhatsApp("+15550001234")
    }
};

await _notifier.SendAsync(payload);

5. Real-Time Web Notification (SignalR)

var payload = new NotificationPayload
{
    Subject = "Export Complete",
    Body = "Your data export is ready to download.",
    Recipients = new List<Recipient>
    {
        Recipient.Client("user-123-id") // Targets a specific user on frontend
    }
};

await _notifier.SendAsync(payload);

Live Dashboard & Monitoring

The library supports real-time monitoring via SignalR. When enabled, the worker broadcasts every event (Success/Failure) to your frontend.

Implement INotificationLiveMonitor in your Web API.
Register it as a Singleton.
Connect your React/Angular frontend to the SignalR Hub.

(See the samples folder for a full dashboard implementation)

Supported Providers

Channel	Provider Class	NuGet Dependency	Notes
Email	`SmtpEmailProvider`	Built-in	Standard .NET `SmtpClient`
Email	`SendGridProvider`	`SendGrid`	Uses SendGrid Web API
Email	`MailgunProvider`	`Microsoft.Extensions.Http`	Uses Mailgun API v3
SMS	`TwilioSmsProvider`	`Twilio`	Standard SMS
SMS	`VonageSmsProvider`	Built-in	Uses Nexmo/Vonage REST API
WhatsApp	`TwilioWhatsAppProvider`	`Twilio`	Requires WhatsApp Sandbox/Number
WhatsApp	`VonageWhatsAppProvider`	Built-in	Requires WhatsApp Sandbox/Number
Slack	`SlackProvider`	Built-in	Uses Incoming Webhooks (Block Kit)
Teams	`TeamsProvider`	Built-in	Uses Incoming Webhooks (MessageCard)
Telegram	`TelegramProvider`	Built-in	Uses Telegram Bot API
Realtime	`SignalRProvider`	`Microsoft.AspNetCore.SignalR.Core`	Pushes to connected clients

The Ecosystem

Package	Description
`Easy.Notifications.Core`	Abstractions, Interfaces, and Models.
`Easy.Notifications`	(You are here) The main engine and default providers.
`Easy.Notifications.Persistence.EntityFramework`	Persistence layer for logging, status tracking, and retry mechanisms.

Contributing

Contributions and suggestions are welcome. Please open an issue or submit a pull request.

Contact

For questions, contact us via elmin.alirzayev@gmail.com or GitHub.

License

This project is licensed under the MIT License.

Product	Compatible and additional computed target framework versions.
.NET	net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.
.NET Core	netcoreapp3.0 was computed. netcoreapp3.1 was computed.
.NET Standard	netstandard2.1 is compatible.
.NET Framework	net47 is compatible. net471 was computed. net472 was computed. net48 is compatible. net481 was computed.
MonoAndroid	monoandroid was computed.
MonoMac	monomac was computed.
MonoTouch	monotouch was computed.
Tizen	tizen60 was computed.
Xamarin.iOS	xamarinios was computed.
Xamarin.Mac	xamarinmac was computed.
Xamarin.TVOS	xamarintvos was computed.
Xamarin.WatchOS	xamarinwatchos was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

.NETFramework 4.7
- Easy.Notifications.Infrastructure (>= 1.0.0)
- Microsoft.AspNetCore.SignalR (>= 1.2.9)
- Microsoft.Extensions.Caching.Memory (>= 10.0.2)
- Microsoft.Extensions.Http (>= 9.0.7)
- Microsoft.Extensions.Logging (>= 9.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 9.0.8)
- SendGrid (>= 9.29.3)
- SendGrid.Extensions.DependencyInjection (>= 1.0.1)
- System.Text.Json (>= 10.0.2)
- Twilio (>= 7.14.2)
- Vonage (>= 8.2.0)
.NETFramework 4.8
- Easy.Notifications.Infrastructure (>= 1.0.0)
- Microsoft.AspNetCore.SignalR (>= 1.2.9)
- Microsoft.Extensions.Caching.Memory (>= 10.0.2)
- Microsoft.Extensions.Http (>= 9.0.7)
- Microsoft.Extensions.Logging (>= 9.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 9.0.8)
- SendGrid (>= 9.29.3)
- SendGrid.Extensions.DependencyInjection (>= 1.0.1)
- System.Text.Json (>= 10.0.2)
- Twilio (>= 7.14.2)
- Vonage (>= 8.2.0)
.NETStandard 2.1
- Easy.Notifications.Infrastructure (>= 1.0.0)
- Microsoft.AspNetCore.SignalR (>= 1.2.9)
- Microsoft.Extensions.Caching.Memory (>= 10.0.2)
- Microsoft.Extensions.Http (>= 9.0.7)
- Microsoft.Extensions.Logging (>= 9.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 9.0.8)
- SendGrid (>= 9.29.3)
- SendGrid.Extensions.DependencyInjection (>= 1.0.1)
- System.Text.Json (>= 10.0.2)
- Twilio (>= 7.14.2)
- Vonage (>= 8.2.0)
net10.0
- Easy.Notifications.Infrastructure (>= 1.0.0)
- Microsoft.AspNetCore.SignalR (>= 1.2.9)
- Microsoft.Extensions.Caching.Memory (>= 10.0.2)
- Microsoft.Extensions.Http (>= 10.0.2)
- Microsoft.Extensions.Logging (>= 10.0.2)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.2)
- SendGrid (>= 9.29.3)
- SendGrid.Extensions.DependencyInjection (>= 1.0.1)
- Twilio (>= 7.14.2)
- Vonage (>= 8.21.0)
net6.0
- Easy.Notifications.Infrastructure (>= 1.0.0)
- Microsoft.AspNetCore.SignalR (>= 1.2.9)
- Microsoft.Extensions.Caching.Memory (>= 10.0.2)
- Microsoft.Extensions.Http (>= 7.0.0)
- Microsoft.Extensions.Logging (>= 7.0.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 7.0.0)
- SendGrid (>= 9.29.3)
- SendGrid.Extensions.DependencyInjection (>= 1.0.1)
- System.Text.Json (>= 8.0.5)
- Twilio (>= 7.14.2)
- Vonage (>= 6.12.0)
net7.0
- Easy.Notifications.Infrastructure (>= 1.0.0)
- Microsoft.AspNetCore.SignalR (>= 1.2.9)
- Microsoft.Extensions.Caching.Memory (>= 10.0.2)
- Microsoft.Extensions.Http (>= 7.0.0)
- Microsoft.Extensions.Logging (>= 7.0.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 7.0.0)
- SendGrid (>= 9.29.3)
- SendGrid.Extensions.DependencyInjection (>= 1.0.1)
- System.Text.Json (>= 8.0.5)
- Twilio (>= 7.14.2)
- Vonage (>= 6.12.0)
net8.0
- Easy.Notifications.Infrastructure (>= 1.0.0)
- Microsoft.AspNetCore.SignalR (>= 1.2.9)
- Microsoft.Extensions.Caching.Memory (>= 10.0.2)
- Microsoft.Extensions.Http (>= 9.0.7)
- Microsoft.Extensions.Logging (>= 9.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 9.0.8)
- SendGrid (>= 9.29.3)
- SendGrid.Extensions.DependencyInjection (>= 1.0.1)
- System.Text.Json (>= 10.0.2)
- Twilio (>= 7.14.2)
- Vonage (>= 8.2.0)
net9.0
- Easy.Notifications.Infrastructure (>= 1.0.0)
- Microsoft.AspNetCore.SignalR (>= 1.2.9)
- Microsoft.Extensions.Caching.Memory (>= 10.0.2)
- Microsoft.Extensions.Http (>= 9.0.7)
- Microsoft.Extensions.Logging (>= 9.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 9.0.8)
- SendGrid (>= 9.29.3)
- SendGrid.Extensions.DependencyInjection (>= 1.0.1)
- System.Text.Json (>= 10.0.2)
- Twilio (>= 7.14.2)
- Vonage (>= 8.2.0)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.2.0	134	2/6/2026
1.1.0	119	2/4/2026
1.0.14	116	1/23/2026
1.0.13	115	1/23/2026
1.0.11	238	8/11/2025
1.0.7	258	8/8/2025
1.0.6	289	8/8/2025
1.0.5	283	8/8/2025