CloudNotify.Sdk 1.0.0

CloudNotify .NET SDK

CloudNotify is a unified communication and notification platform SDK for .NET. It abstracts away multiple notification channels (Email, SMS, WhatsApp, and Push Notifications) and their respective providers behind a single, consistent client interface.

Table of Contents

1. Supported Channels & Providers
2. Installation
3. SDK Client Registration & Setup
   • Direct Setup (No DI)
   • Microsoft Dependency Injection Setup (ASP.NET Core)
4. Provider Credential Registration & Platform Setup Guide
   • SMTP (Generic / Mailtrap / Gmail)
   • SendGrid
   • Mailgun
   • Amazon SES
   • Azure Communication Services (ACS) Email
   • Microsoft Graph Mail (Office 365)
   • Twilio SMS
   • Azure Communication Services (ACS) SMS
   • Meta WhatsApp Cloud API
   • Firebase Cloud Messaging (FCM) Push
5. Method & Channel API Reference
   • Email Channel Methods
   • SMS Channel Methods
   • WhatsApp Channel Methods
   • Push Channel Methods
6. Extensibility: Custom Providers
7. Running Tests & Samples

Supported Channels & Providers

Installation

Add the project reference to your application, or package it into a NuGet package:

# Add package reference (if published to a NuGet registry)
dotnet add package CloudNotify

SDK Client Registration & Setup

Direct Setup (No DI)

Use CloudNotifyClient.Create in non-DI apps:

using CloudNotify;
using CloudNotify.Configuration;

var client = CloudNotifyClient.Create(config =>
{
    // Register Email
    config.UseSmtp(options => 
    {
        options.Host = "smtp.mailtrap.io";
        options.Port = 587;
        options.Username = "user";
        options.Password = "pass";
    }, name: "Smtp", isDefault: true);

    config.UseSendGrid(options => options.ApiKey = "SG.xxxx");

    // Register SMS
    config.UseTwilioSms(options => 
    {
        options.AccountSid = "ACxxx";
        options.AuthToken = "token";
    }, isDefault: true);

    // Register WhatsApp
    config.UseMetaWhatsApp(options => 
    {
        options.AccessToken = "access-token";
        options.DefaultPhoneNumberId = "phone-id";
    }, isDefault: true);

    // Register Push
    config.UseFirebasePush(options => 
    {
        options.CredentialJson = "service-account-json-content";
    }, isDefault: true);
});

Dependency Injection Setup (ASP.NET Core)

Configure services in your ASP.NET Core Program.cs:

using Microsoft.Extensions.DependencyInjection;

builder.Services.AddCloudNotify(config =>
{
    config.AddSmtp(options => 
    {
        options.Host = "smtp.mailtrap.io";
        options.Port = 587;
        options.Username = "user";
        options.Password = "pass";
    }, isDefault: true);

    config.AddSendGrid(options => options.ApiKey = "SG.xxxx");
    config.AddTwilioSms(options => 
    {
        options.AccountSid = "ACxxx";
        options.AuthToken = "token";
    }, isDefault: true);
    config.AddMetaWhatsApp(options => 
    {
        options.AccessToken = "access-token";
        options.DefaultPhoneNumberId = "phone-id";
    }, isDefault: true);
    config.AddFirebasePush(options => 
    {
        options.CredentialJson = "service-account-json";
    }, isDefault: true);
});

Provider Credential Registration & Platform Setup Guide

Before invoking the registration extensions, configure your accounts on each platform to obtain the necessary credentials.

1. SMTP (Generic / Mailtrap / Gmail)

• Registration: Get an SMTP account from any standard email provider, or sign up for Mailtrap for development sandboxing.
• Config Properties:
  • Host: Domain name of the SMTP server (e.g., smtp.mailtrap.io).
  • Port: Server port, usually 587 (TLS) or 465 (SSL).
  • Username: SMTP auth username.
  • Password: SMTP auth password.
  • UseSsl: Set true if utilizing SSL wrapper port (465), or false for StartTLS (587).
• Code Register:

  config.UseSmtp(o => { o.Host = "smtp.mailtrap.io"; o.Port = 587; o.Username = "user"; o.Password = "pass"; o.UseSsl = false; }, "MailtrapSmtp", isDefault: true);
  

2. SendGrid

• Registration: Create an account on SendGrid. Go to Settings > API Keys and click Create API Key.
• Config Properties:
  • ApiKey: The secret key starting with SG..
• Code Register:

  config.UseSendGrid(o => o.ApiKey = "SG.xxxxx", "SendGrid", isDefault: false);
  

3. Mailgun

• Registration: Sign up at Mailgun. Create a sending domain in Sending > Domains. Retrieve your sending API key in Settings > API Keys.
• Config Properties:
  • ApiKey: The secret Mailgun API key.
  • Domain: The registered active domain name.
  • UseEuRegion: Set true if your account uses EU API endpoints (https://api.eu.mailgun.net), otherwise false.
• Code Register:

  config.UseMailgun(o => { o.ApiKey = "key-xxxx"; o.Domain = "sandbox123.mailgun.org"; o.UseEuRegion = false; }, "Mailgun");
  

4. Amazon SES

• Registration: Sign up for AWS SES Console. Verify your domain or sender email address. Go to AWS IAM Console to create a user with AmazonSESFullAccess and retrieve credentials.
• Config Properties:
  • AccessKey: AWS Access Key ID.
  • SecretKey: AWS Secret Access Key.
  • Region: AWS System region name (e.g., us-east-1, eu-west-1).
• Code Register:

  config.UseAmazonSes(o => { o.AccessKey = "AKIAxxx"; o.SecretKey = "secretxxx"; o.Region = "us-east-1"; }, "AmazonSes");
  

5. Azure Communication Services (ACS) Email

• Registration: Create an Azure Communication Services resource in the Azure Portal. Provision an Email Communication Service resource and link it. Retrieve your resource connection string from the Keys tab.
• Config Properties:
  • ConnectionString: Full connection string (e.g., endpoint=https://xxx.communication.azure.com/;accesskey=xxx).
• Code Register:

  config.UseAzureAcsEmail(o => o.ConnectionString = "endpoint=...", "AzureAcsEmail");
  

6. Microsoft Graph Mail (Office 365)

• Registration: Register an app in your Azure Active Directory (Microsoft Entra ID) via the App Registrations portal. Grant Mail.Send Application permission and create a client secret. Note your Tenant ID, Client ID, Client Secret, and the email of the sender mailbox.
• Config Properties:
  • TenantId: Entra Directory Tenant GUID.
  • ClientId: Registered App Application Client GUID.
  • ClientSecret: Client Secret secret value string.
  • SenderUserId: Email address or User Object GUID of the mailbox from which to send (e.g. sender@mytenant.com).
• Code Register:

  config.UseMsGraphEmail(o => { o.TenantId = "tenant-id"; o.ClientId = "client-id"; o.ClientSecret = "secret"; o.SenderUserId = "user@tenant.com"; }, "MsGraph");
  

7. Twilio SMS

• Registration: Create an account on Twilio. Purchase a phone number or register a sender identifier. Copy your Account SID and Auth Token from your console home dashboard.
• Config Properties:
  • AccountSid: Twilio Account SID.
  • AuthToken: Twilio Authorization Token.
• Code Register:

  config.UseTwilioSms(o => { o.AccountSid = "ACxxx"; o.AuthToken = "token"; }, "Twilio", isDefault: true);
  

8. Azure Communication Services (ACS) SMS

• Registration: Create an Azure Communication Services resource. Rent an SMS-enabled phone number. Copy the connection string from the Keys tab.
• Config Properties:
  • ConnectionString: Full Azure ACS connection string.
• Code Register:

  config.UseAzureAcsSms(o => o.ConnectionString = "endpoint=...", "AzureAcsSms");
  

9. Meta WhatsApp Cloud API

• Registration: Set up a Meta developer account and create a Business App on the Meta App Dashboard. Add WhatsApp configuration to the app. Get a Temporary or Permanent Access Token and your Phone Number ID (a numeric string representing the sender number, separate from the actual number).
• Config Properties:
  • AccessToken: The System User token.
  • DefaultPhoneNumberId: The default Phone Number ID from the dashboard setup tab.
• Code Register:

  config.UseMetaWhatsApp(o => { o.AccessToken = "meta-token"; o.DefaultPhoneNumberId = "1028392183921"; }, "MetaWhatsApp", isDefault: true);
  

10. Firebase Cloud Messaging (FCM) Push

• Registration: Create a Firebase project in Firebase Console. Go to Project Settings > Service Accounts. Click Generate new private key and download the credentials JSON file.
• Config Properties:
  • CredentialJson: Contents of the service account JSON file.
  • CredentialFilePath: Path to the service account JSON file (alternative).
  • AppName: Name of the Firebase app instance (defaults to [DEFAULT]).
• Code Register:

  config.UseFirebasePush(o => { o.CredentialJson = "{ \"type\": \"service_account\", ... }"; }, "FirebasePush", isDefault: true);
  

Method & Channel API Reference

The SDK exposes four main channel gateways under ICloudNotifyClient: Email, Sms, WhatsApp, and Push.

Email Channel Methods

Exposed via client.Email. Deals with EmailMessage models.

Method 1: Send via Default Email Provider

Sends the message utilizing the registered provider flagged as default.

Task<SendResult> SendAsync(EmailMessage message, CancellationToken cancellationToken = default);

• Example:

  var msg = new EmailMessage
  {
      From = "no-reply@company.com",
      Subject = "Status Update",
      Body = "<p>All systems operational.</p>",
      IsHtml = true
  };
  msg.To.Add("user@test.com");
  
  SendResult result = await client.Email.SendAsync(msg);
  Console.WriteLine($"Sent: {result.IsSuccess}. Provider: {result.ProviderName}. Id: {result.MessageId}");
  

Method 2: Send via Specific Named Email Provider

Sends the message utilizing a specific named provider regardless of default configuration.

Task<SendResult> SendAsync(EmailMessage message, string providerName, CancellationToken cancellationToken = default);

• Example:

  // Force sending via SendGrid rather than default SMTP
  SendResult result = await client.Email.SendAsync(msg, "SendGrid");
  

SMS Channel Methods

Exposed via client.Sms. Deals with SmsMessage models.

Method 1: Send via Default SMS Provider

Task<SendResult> SendAsync(SmsMessage message, CancellationToken cancellationToken = default);

• Example:

  var sms = new SmsMessage
  {
      From = "+1234567890", // Twilio number or Sender ID
      To = "+19876543210",  // Recipient in E.164 format
      Body = "Code: 4831"
  };
  SendResult result = await client.Sms.SendAsync(sms);
  

Method 2: Send via Specific Named SMS Provider

Task<SendResult> SendAsync(SmsMessage message, string providerName, CancellationToken cancellationToken = default);

• Example:

  // Force sending via Azure ACS SMS instead of Twilio
  SendResult result = await client.Sms.SendAsync(sms, "AzureAcsSms");
  

WhatsApp Channel Methods

Exposed via client.WhatsApp. Deals with WhatsAppMessage models.

Method 1: Send via Default WhatsApp Provider

Task<SendResult> SendAsync(WhatsAppMessage message, CancellationToken cancellationToken = default);

• Example (Template Message):

  var wa = new WhatsAppMessage
  {
      To = "+19876543210",
      TemplateName = "alert_notification",
      TemplateLanguage = "en_US"
  };
  wa.TemplateParameters.Add("Server A"); // Parameter {1}
  wa.TemplateParameters.Add("Offline");  // Parameter {2}
  
  SendResult result = await client.WhatsApp.SendAsync(wa);
  

• Example (Free-text Session Message):

  var wa = new WhatsAppMessage
  {
      To = "+19876543210",
      Body = "Hello, how can I assist you?"
  };
  SendResult result = await client.WhatsApp.SendAsync(wa);
  

Method 2: Send via Specific Named WhatsApp Provider

Task<SendResult> SendAsync(WhatsAppMessage message, string providerName, CancellationToken cancellationToken = default);

• Example:

  SendResult result = await client.WhatsApp.SendAsync(wa, "MetaWhatsApp");
  

Push Channel Methods

Exposed via client.Push. Deals with PushMessage models.

Method 1: Send via Default Push Provider

Task<SendResult> SendAsync(PushMessage message, CancellationToken cancellationToken = default);

• Example (Device Token Target):

  var push = new PushMessage
  {
      Token = "fcm-registration-device-token",
      Title = "New Alert",
      Body = "Task #481 has been completed."
  };
  push.Data.Add("Priority", "High");
  
  SendResult result = await client.Push.SendAsync(push);
  

• Example (Topic Target - Broadcast):

  var push = new PushMessage
  {
      Topic = "system_alerts",
      Title = "Maintenance Scheduled",
      Body = "System will be down for maintenance tonight at 10 PM."
  };
  SendResult result = await client.Push.SendAsync(push);
  

Method 2: Send via Specific Named Push Provider

Task<SendResult> SendAsync(PushMessage message, string providerName, CancellationToken cancellationToken = default);

• Example:

  SendResult result = await client.Push.SendAsync(push, "FirebasePush");
  

Extensibility: Adding Custom Providers

You can extend the SDK by implementing provider interfaces.

Example: Custom SMS Provider

1. Declare options:

public class MyCustomSmsOptions { public string ApiKey { get; set; } }

2. Implement ISmsProvider:

using CloudNotify.Abstractions;
using CloudNotify.Models;

public class MyCustomSmsProvider : ISmsProvider
{
    private readonly MyCustomSmsOptions _options;
    public string Name => "MyCustomSms";

    public MyCustomSmsProvider(MyCustomSmsOptions options) => _options = options;

    public async Task<SendResult> SendAsync(SmsMessage message, CancellationToken cancellationToken = default)
    {
        // Invoke custom service API via HttpClient
        return SendResult.Success("msg-id-999", Name);
    }
}

3. Register with client:

// Standalone
var client = CloudNotifyClient.Create(config =>
{
    config.SmsProviders.Add(new MyCustomSmsProvider(new MyCustomSmsOptions { ApiKey = "xxx" }));
});

// Dependency Injection
services.AddTransient<ISmsProvider>(sp => new MyCustomSmsProvider(new MyCustomSmsOptions { ApiKey = "xxx" }));

Running Tests & Samples

Run Automated Tests

dotnet test

Run Sample Interactive Application

dotnet run --project samples/CloudNotify.Sample/CloudNotify.Sample.csproj