Notifications

The client.Notifications sub-client covers sending notifications and querying their status.

Available methods

Channels

Channels are represented by the typed Channel enum in OneSend2U.Sdk.Models.Enums:

The enum serializes to/from the lowercase wire codes shown above (case-insensitive on read), so the JSON payloads sent and received by the API are unchanged. Use the enum members anywhere a Channel? property appears:

using OneSend2U.Sdk.Models.Enums;
using OneSend2U.Sdk.Notifications.Models;

new NotificationRecipient { Channel = Channel.Sms, Recipient = "+34915794174" };
new TargetChannel        { Channel = Channel.Email };
new ContactGroupTarget   { Code = "VIP", Channel = Channel.WhatsApp };

For dictionary keys (e.g., SenderOverrides) the key type is still string — System.Text.Json does not serialize enum keys. Use the ChannelCodes constants to keep the wire codes consistent:

using OneSend2U.Sdk.Models.Enums;

SenderOverrides = new Dictionary<string, SenderOverride>
{
    [ChannelCodes.Sms]   = new() { Address = "+34915794174" },
    [ChannelCodes.Email] = new() { Address = "security@verified.com" }
};

ChannelCodes also exposes helpers — ChannelCodes.ToWireCode(Channel) for query strings and ChannelCodes.FromWireCode(string?) for case-insensitive parsing of incoming codes.

Sending a notification

Request model

SendNotificationRequest fields:

NotificationRecipient

NotificationAttachment

ContactGroupTarget

TargetChannel

Send example

using OneSend2U.Sdk.Models.Enums;
using OneSend2U.Sdk.Notifications.Models;

var response = await client.Notifications.SendAsync(new SendNotificationRequest
{
    TransactionId       = Guid.NewGuid().ToString(),
    Application         = "billing",
    Region              = "us",
    Language            = "en",
    NotificationType    = "trans",
    NotificationSubtype = "invoice",
    Recipients =
    [
        new NotificationRecipient { Channel = Channel.Sms,   Recipient = "+15550001234" },
        new NotificationRecipient { Channel = Channel.Email, Recipient = "jane@example.com" }
    ],
    TemplateVariables =
    [
        new Dictionary<string, string>
        {
            ["customer_name"]  = "Jane Doe",
            ["invoice_number"] = "INV-001",
            ["amount"]         = "$120.00"
        }
    ]
});

Console.WriteLine($"Status: {response.Status}");
Console.WriteLine($"Created: {response.CreatedAt:O}");

if (response.Warnings?.Count > 0)
    foreach (var w in response.Warnings)
        Console.WriteLine($"Warning: {w}");

Sending to Contact Groups

You can send to all members of one or more contact groups by specifying their codes. Group members are resolved server-side — no need to query the group and build the recipients list manually.

// Send to a contact group (all TargetChannels)
var response = await client.Notifications.SendAsync(new SendNotificationRequest
{
    TransactionId       = Guid.NewGuid().ToString(),
    Application         = "billing",
    Region              = "us",
    Language            = "en",
    NotificationType    = "trans",
    NotificationSubtype = "invoice",
    TargetChannels      = [new TargetChannel { Channel = Channel.Email }],
    ContactGroupCodes   =
    [
        new ContactGroupTarget { Code = "VIP" }  // all TargetChannels
    ],
    TemplateVariables =
    [
        new Dictionary<string, string>
        {
            ["customer_name"] = "Valued Customer",
            ["invoice_number"] = "INV-001"
        }
    ]
});

You can also mix explicit recipients with contact groups. Duplicates are automatically removed by (channel, destination):

// Mix explicit recipients + contact groups with channel filter
var response = await client.Notifications.SendAsync(new SendNotificationRequest
{
    TransactionId       = Guid.NewGuid().ToString(),
    Application         = "billing",
    Region              = "us",
    Language            = "en",
    NotificationType    = "trans",
    NotificationSubtype = "invoice",
    TargetChannels      =
    [
        new TargetChannel { Channel = Channel.Email },
        new TargetChannel { Channel = Channel.Sms }
    ],
    Recipients =
    [
        new NotificationRecipient { Channel = Channel.Email, Recipient = "cfo@example.com" }
    ],
    ContactGroupCodes =
    [
        new ContactGroupTarget { Code = "FINANCE", Channel = Channel.Email },  // email only
        new ContactGroupTarget { Code = "MGMT" }                               // all channels
    ],
    TemplateVariables =
    [
        new Dictionary<string, string>
        {
            ["customer_name"] = "Team",
            ["invoice_number"] = "INV-002"
        }
    ]
});

Note: If a contact group code does not exist or has no members, a warning is included in the response but the notification is still processed for any valid recipients (partial success). Contacts without the required channel data (e.g., no phone number for SMS) are silently skipped.

Response model

SendNotificationResponse fields:

Sender override

The default sender per channel is configured at the application level (Communication Channels tab). For one-off requests you can override it with the SenderOverrides map — keyed by channel code (ChannelCodes.Sms, ChannelCodes.Email, ChannelCodes.WhatsApp; the wire format is the lowercase code, case-insensitive on read). Each entry carries an optional Address and/or Name. Per-channel rules:

An entry with both Address and Name null/whitespace is rejected with Cpaas:SenderOverride:00012 (SenderOverrideEmpty).

The override applies to the whole notification (all recipients in the request). Resolution priority (most specific wins): API request → Application channel default → Connection default sender.

using OneSend2U.Sdk.Models.Enums;

// Email — override From address and name for this request only
var response = await client.Notifications.SendAsync(new SendNotificationRequest
{
    TransactionId       = Guid.NewGuid().ToString(),
    Application         = "billing",
    Region              = "us",
    Language            = "en",
    NotificationType    = "trans",
    NotificationSubtype = "reset_pwd",
    TargetChannels      = [new TargetChannel { Channel = Channel.Email }],
    Recipients          = [new NotificationRecipient { Channel = Channel.Email, Recipient = "jane@example.com" }],
    SenderOverrides     = new()
    {
        [ChannelCodes.Email] = new SenderOverride
        {
            Address = "security@your-verified-domain.com",
            Name    = "Acme Security"
        }
    },
    TemplateVariables   = [new Dictionary<string, string> { ["reset_link"] = "https://..." }]
});

// SMS — pick a specific sender from the connection's available list and apply a display name
var response = await client.Notifications.SendAsync(new SendNotificationRequest
{
    TransactionId       = Guid.NewGuid().ToString(),
    Application         = "billing",
    Region              = "us",
    Language            = "en",
    NotificationType    = "trans",
    NotificationSubtype = "otp",
    TargetChannels      = [new TargetChannel { Channel = Channel.Sms }],
    Recipients          = [new NotificationRecipient { Channel = Channel.Sms, Recipient = "+15550001234" }],
    SenderOverrides     = new()
    {
        [ChannelCodes.Sms] = new SenderOverride
        {
            Address = "+34915794174",   // must exist in Connection.Senders[].Address
            Name    = "Acme"            // best-effort: dropped on countries that don't support alpha
        }
    },
    TemplateVariables   = [new Dictionary<string, string> { ["code"] = "482910" }]
});

Migration from SDK 1.x

SDK 1.x exposed flat SenderAddress / SenderName fields on SendNotificationRequest. SDK 2.0.0 replaces them with SenderOverrides:

using OneSend2U.Sdk.Models.Enums;

// SDK 1.x
req.SenderAddress = "security@verified.com";
req.SenderName    = "Acme Security";

// SDK 2.0+
req.SenderOverrides = new()
{
    [ChannelCodes.Email] = new SenderOverride { Address = "security@verified.com", Name = "Acme Security" }
};

SDK 2.1 note: the Channel properties (NotificationRecipient.Channel, TargetChannel.Channel, ContactGroupTarget.Channel) are now the typed Channel? enum instead of string?. Wire format on the API is unchanged. SenderOverrides keys are still string (System.Text.Json limitation); use ChannelCodes constants instead of string literals.

Sending with attachments (Email)

using OneSend2U.Sdk.Models.Enums;

var response = await client.Notifications.SendAsync(new SendNotificationRequest
{
    TransactionId       = Guid.NewGuid().ToString(),
    Application         = "billing",
    Region              = "us",
    Language            = "en",
    NotificationType    = "trans",
    NotificationSubtype = "invoice",
    TargetChannels      = [new TargetChannel { Channel = Channel.Email }],
    Recipients          = [new NotificationRecipient { Channel = Channel.Email, Recipient = "jane@example.com" }],
    TemplateVariables   = [new Dictionary<string, string> { ["invoice_number"] = "INV-001" }],
    Attachments =
    [
        new NotificationAttachment
        {
            FileName    = "invoice-001.pdf",
            FileContent = Convert.ToBase64String(pdfBytes)
        }
    ]
});

Querying notifications

List notifications

using OneSend2U.Sdk.Notifications.Models;

var list = await client.Notifications.GetListAsync(new GetNotificationsRequest
{
    SkipCount      = 0,
    MaxResultCount = 20
});

Console.WriteLine($"Total: {list.TotalCount}");
foreach (var notification in list.Items)
    Console.WriteLine($"{notification.Id} — {notification.Status}");

GetListAsync returns PagedResult<NotificationWithDetailsResponse> with:

Get a single notification

var notification = await client.Notifications.GetAsync(notificationId);
Console.WriteLine($"Status: {notification.Status}");

Get notification with navigation properties

Returns the notification along with its related lookup data (application, type, subtype, country, environment, and channel types).

GetWithDetailsAsync returns NotificationWithDetailsResponse with:

NotificationResponse fields:

LookupItem fields:

var details = await client.Notifications.GetWithDetailsAsync(notificationId);

// Access the base notification data through details.Notification
Console.WriteLine($"Status: {details.Notification.Status}");
Console.WriteLine($"Messages sent: {details.Notification.NumberOfSuccessMessages}/{details.Notification.NumberOfTotalMessages}");

// Access related lookup data
Console.WriteLine($"Application: {details.Application?.Name}");
Console.WriteLine($"Country: {details.Country?.Code}");
Console.WriteLine($"Environment: {details.DeploymentEnvironment?.Name}");

// List the channels used
foreach (var channel in details.ChannelTypes ?? [])
    Console.WriteLine($"Channel: {channel.DisplayName}");

Filter parameters

GetNotificationsRequest supports the following filters: