IlluminatingSoftware.MessageService.Client 1.1.1

MessageService.Client

A typed .NET HTTP client for the MessageService email and SMS sending API.

Targets .NET 8+ and .NET Framework 4.6.2+.

Installation

dotnet add package IlluminatingSoftware.MessageService.Client

Usage

Register the client with dependency injection using Basic-Auth credentials issued by the MessageService admin portal:

services.AddMessageServiceClient(options =>
{
    options.BaseUrl = new Uri("https://messageservice.example.com/");
    options.Username = "your-client-username";
    options.Password = "your-client-password";
});

Then inject IMessageServiceClient wherever you need it:

public class NotificationService
{
    private readonly IMessageServiceClient _client;

    public NotificationService(IMessageServiceClient client)
    {
        _client = client;
    }

    public Task SendWelcomeEmailAsync(string to)
    {
        return _client.SendEmailAsync(new SendEmailRequest
        {
            ToAddresses = new[] { to },
            Subject = "Welcome!",
            Body = "Thanks for signing up."
        });
    }
}

Tracking sent and read events

Set your own ids when sending. The service stores them and records events as the email is sent, read (tracking pixel), or fails.

• MessageId — your id for one email. Use it later to pull that email's events.
• GroupMessageId — your id for a batch or campaign. Set the same value on every email in the group, then pull all of their events in one call.

MessageId is stored as RequesterMsgId (that field already existed). GroupMessageId is new. Both are optional Guid? values.

var messageId = Guid.NewGuid();
var groupId = campaignId; // one id shared by every email in this send

await _client.SendEmailAsync(new SendEmailRequest
{
    ToAddresses = new[] { to },
    Subject = "Welcome!",
    Body = "Thanks for signing up.",
    MessageId = messageId,
    GroupMessageId = groupId,
});

// Later — one email
var one = await _client.GetEmailEventsByMessageIdAsync(messageId);
Console.WriteLine($"sent={one.Messages[0].WasSent} read={one.Messages[0].WasRead}");
foreach (var ev in one.Messages[0].Events)
    Console.WriteLine($"{ev.ActionTimeUtc:u} {ev.Action}");

// Later — every email in the campaign
var group = await _client.GetEmailEventsByGroupMessageIdAsync(groupId);
foreach (var email in group.Messages)
    Console.WriteLine($"{email.Subject}: sent={email.WasSent} read={email.WasRead} last={email.LatestAction}");

Each result includes:

Lookups are scoped to your API client. Results are capped at 500 emails per call.

You can also load a single email (including its events) by the service-assigned id returned from SendEmailAsync:

var record = await _client.GetEmailAsync(sent.Id);
foreach (var ev in record.MessageEvents)
    Console.WriteLine($"{ev.ActionTimeUtc:u} {ev.Action}");

API

• SendEmailAsync / GetEmailAsync / GetEmailsAsync
• GetEmailEventsByMessageIdAsync / GetEmailEventsByGroupMessageIdAsync
• SendSmsAsync / GetSmsMessageAsync / GetSmsMessagesAsync

License

Licensed under the MIT License, © Illuminating Software LLC.

Package Maintainer

Published to NuGet.org under the Splat account (trent@zfairs.com).