DEV Community: Jeremy

Part 5: After the Dispatch - Handling Delivery Events

Jeremy — Thu, 22 Oct 2026 23:00:00 +0000

Part 4 ended on one word in the Communications logs:

[Email:Simulation.Email:Dispatched] ...
[Sms:Simulation.Sms:Dispatched] ...
[Push:Simulation.Push:Dispatched] ...

Dispatched means a provider accepted the message. It doesn't mean anyone received it.

With the simulator the two happen together. With a real provider they don't. Twilio accepts an SMS and returns a message id straight away, then reports back as the message moves along: queued, sent, delivered, or undelivered because the handset was unreachable. Email providers report bounces and opens. Push services report invalid tokens.

Those updates are worth keeping. Support wants to know whether the customer really got the order confirmation. Engineering wants to know which provider is failing. And customers like being able to see what a business has sent them.

This article captures those delivery events in Communications, stores them, and puts them in front of the buyer on a new Messages page.

Ordering still doesn't change

As in Part 4, nothing in this article touches Ordering. It dispatches OrderCreated exactly as it did in Part 3. Delivery events describe what happened to a communication after Ordering stated its intent, and that's Communications' business.

One message per buyer

Part 4 used the any-match strategy so we could watch all three channels go out at once. For an order confirmation, that's three messages where one would do. Part 5 goes back to Transmitly's default, first match: each buyer gets one message, on the first channel in the pipeline that can reach them.

OrderCreated
    |
    +-- Email  verified email address?  deliver and stop
    |
    +-- SMS    verified phone number?   deliver and stop
    |
    +-- Push   registered device?       deliver

Which channel that is depends on the buyer. Communications now only uses addresses the buyer has verified. The resolver drops the rest before any channel sees them:

var addresses = profile.Addresses
    .Where(address => address.IsVerified)
    .Select(address => ...);

eShop's two seeded buyers are set up to show the difference. Alice has verified her email address but not her phone number. Bob has verified his phone number but not his email address. (The seed only creates users that don't exist yet. If your identitydb was seeded by an earlier part, the Part 5 README has the SQL to update bob.)

                         Ordering
                            |
           OrderCreated + buyer reference
                            |
               +------------+------------+
               |                         |
             alice                      bob
               |                         |
    resolves to a verified     resolves to a verified
        email address               phone number
               |                         |
               v                         v
             Email                      SMS

Ordering sent exactly the same intent for both. It never knew an email address or a phone number existed. Communications resolved each buyer and picked the channel.

In Part 2, Ordering handed over an email address, so every order confirmation was an email. That coupling went away in Part 3, and now the buyer's verified addresses decide.

What a delivery report is

Transmitly represents every delivery event the same way, whatever provider it came from:

public record DeliveryReport(
    string EventName,
    string? ChannelId,
    string? ChannelProviderId,
    string? PipelineIntent,
    string? PipelineId,
    string? ResourceId,
    CommunicationsStatus Status,
    object? ChannelCommunication,
    IContentModel? ContentModel,
    Exception? Exception);

A few of those fields do most of the work:

EventName           what happened: OnDispatched, OnStatusChanged, OnDelivered, OnError
ChannelId           Email, Sms, Push
ChannelProviderId   who reported it: Simulation.Sms, Twilio, ...
ResourceId          the provider's id for the message
Status              a provider-agnostic outcome, with a success or failure range

That's half of what this article is about. Code that records, displays, or alerts on delivery events can be written once, against DeliveryReport, and work for every provider.

Reports come from two places

Some reports are raised at dispatch. When a provider accepts a message, its Transmitly integration raises an OnDispatched report with the provider's message id. The simulator does the same, which is what produced those log lines.

Others arrive later. A provider like Twilio calls a webhook when a message's status changes, and Transmitly turns that callback into an OnStatusChanged report.

Dispatch
   |
   v
Provider accepts the message ------> OnDispatched report
   |
   | seconds or minutes later
   v
Provider calls our webhook --------> OnStatusChanged report

Both kinds reach the same place. Next to the logging handler from Part 2, Communications registers a delivery report handler for recording:

.AddDeliveryReportHandler(report =>
{
    deliveryReports.Enqueue(report);
    return Task.CompletedTask;
})

It doesn't check which provider sent the report, or whether the report came from a dispatch or a webhook. It just queues it.

Recording reports in the background

The handler only queues because of where reports are raised: in the middle of a dispatch, or in the middle of a webhook request from a provider. Neither is a good place to wait on a database.

A background service reads the queue and records one report at a time:

await foreach (var report in queue.ReadAllAsync(stoppingToken))
{
    await using var scope = scopeFactory.CreateAsyncScope();
    var recorder = scope.ServiceProvider.GetRequiredService<DeliveryReportRecorder>();
    await recorder.RecordAsync(report, stoppingToken);
}

Processing reports in order also means a quick status update can't race the dispatch report it follows. A report that fails to record is logged, and the processor moves on to the next one.

Communications gets a database

Delivery history is communications data, so it goes in a database Communications owns. The AppHost adds communicationsdb to eShop's existing Postgres server, next to the Catalog and Ordering databases:

var communicationsDb = postgres.AddDatabase("communicationsdb");

The model has two tables. A communication is one message to one recipient on one channel, with its latest status. A delivery event is one report about it.

Communications
    Id
    PipelineIntent      OrderCreated
    ChannelId           Sms
    ChannelProviderId   Twilio
    ResourceId          SM8f2c...     the provider's message id
    RecipientId         the buyer's identity
    Summary             "We've received your eShop order #123. ..."
    Status              Delivered
    IsFailure           false

DeliveryEvents
    CommunicationRecordId
    EventName           OnStatusChanged
    Status              Delivered
    ProviderDetails     {"MessageSid": "SM8f2c...", "ErrorCode": null, ...}
    ReceivedAt

The recorder ties reports together through the provider's message id. The first report for a message creates its communication. Later reports with the same channel and message id add events to it:

var record = await FindAsync(report, cancellationToken);

if (record is null)
{
    record = new CommunicationRecord { /* intent, channel, provider, message id ... */ };
    db.Communications.Add(record);
}

// A provider's later update carries less context than the dispatch, so only fill gaps.
record.RecipientId ??= DeliveryReportDetails.RecipientId(report);
record.Summary ??= DeliveryReportDetails.Summary(report.ChannelCommunication);

record.Status = report.Status.Type;
record.IsFailure = report.Status.IsFailure();

The report raised at dispatch knows a lot: the rendered message, the content model, and the recipient profile inside it. A webhook from Twilio knows only its message id and the new status. Filling gaps keeps the richer details from the dispatch.

The latest report wins. Providers don't always report in order, and a production system might want to make sure a late sent never overwrites delivered. For the sample, the simple rule is enough.

Receiving provider webhooks

Transmitly's ASP.NET Core package, Transmitly.Microsoft.AspnetCore.Mvc, supplies a controller for delivery report webhooks. Communications exposes it at one address for every provider:

[AllowAnonymous]
[Route("api/communications/delivery-reports")]
public sealed class DeliveryReportsController(ICommunicationsClient communicationsClient)
    : ChannelProviderDeliveryReportController(communicationsClient);

and registers the model binders that do the actual work:

builder.Services.AddControllers(options => options.AddTransmitlyDeliveryReportModelBinders());

When a request arrives, the binder offers it to each registered provider's request adaptor. Each adaptor recognizes its own provider's requests and turns them into DeliveryReports, which the controller hands back to Transmitly. From there they go to the same handlers as every other report.

POST /api/communications/delivery-reports?...
        |
        v
Delivery report model binder
        |
        +-- Twilio SMS adaptor     "this is mine" -> DeliveryReport
        +-- Twilio voice adaptor   not mine
        +-- ...
        |
        v
Transmitly delivery report handlers
        |
        v
DeliveryReportQueue

The webhook is anonymous because providers can't sign in. A production deployment should validate each provider's request signature before trusting a callback. Twilio's adaptor captures the signature header, but the sample doesn't check it.

Using Twilio as the example

The sample uses Twilio for this part because it's a provider that really does report delivery status after dispatch. It's wired up, but only switched on when credentials are configured:

if (_twilio is null)
{
    builder.AddSimulationSupport(providerId: "Sms");
}
else
{
    builder.AddTwilioSupport(twilio =>
    {
        twilio.AccountSid = _twilio.AccountSid;
        twilio.AuthToken = _twilio.AuthToken;
    });
}

Because the SMS provider now depends on configuration, EshopChannelProviders is no longer Part 4's static class. Program.cs builds it at startup with EshopChannelProviders.FromConfiguration(builder.Configuration), and the pipeline reads each channel's provider id from that instance, as providers.Sms.

Without Twilio settings, SMS stays on the simulator and everything in this article still works. The simulator raises its OnDispatched reports, the recorder stores them, and the Messages page shows them.

With Twilio configured, Twilio also needs to know where to send status updates. The SMS channel tells it, using Twilio's own channel settings:

sms.Twilio().StatusCallbackUrl = providers.DeliveryReportUrl;

When it sends each message, Transmitly gives Twilio the webhook address plus a few query parameters that identify the intent, the channel, and the provider:

https://<public host>/api/communications/delivery-reports
    ?tlyp=OrderCreated
    &tlyc=Sms
    &tlycp=Twilio

Those parameters are how Twilio's adaptor recognizes the callback as its own when it comes back. The address has to be reachable from Twilio's servers, so local development needs a tunnel.

The configuration goes in the Communications API's user secrets or environment variables, and looks like this:

{
  "Twilio": {
    "AccountSid": "AC...",
    "AuthToken": "...",
    "FromNumber": "+1..."
  },
  "Communications": {
    "DeliveryReportUrl": "https://<public host>/api/communications/delivery-reports"
  }
}

Bob's seeded phone number, +11234567890, is in E.164 format, but it isn't a real number. To send him a real text, change it to a number you can receive texts on, also in E.164 format. On a Twilio trial account, it also has to be a number you've verified with Twilio. Otherwise Twilio rejects the message, and first match falls through to push.

Provider details when you need them

The other half of this article is the provider's own detail. A provider-agnostic status is right for almost everything, but sometimes you need to know exactly what the provider said.

When Twilio reports an undelivered SMS, the shared status says the message failed. Twilio's error code says why: 30003 means the handset was unreachable, 30005 means the number doesn't exist, and 30007 means a carrier filtered the message. Each of those calls for a different response.

Transmitly keeps the provider's details on the report, and each provider package exposes them through its own extension. The recorder stores Twilio's alongside the shared status:

if (report.ChannelProviderId?.StartsWith(Id.ChannelProvider.Twilio(), StringComparison.OrdinalIgnoreCase) == true
    && report.ChannelId == Id.Channel.Sms())
{
    var sms = report.Twilio().Sms;
    return JsonSerializer.Serialize(new
    {
        sms.MessageSid,
        MessageStatus = sms.MessageStatus?.ToString(),
        sms.ErrorCode,
        sms.To,
        sms.From
    });
}

That's the only provider-specific code in the recording path, and it's optional. Remove it and every Twilio report is still recorded with its status. Keep it and the details are there for the support engineer who needs them.

The buyer's inbox

With communications stored, the buyer can see them. Communications exposes an inbox for the signed-in user:

endpoints.MapGet("/api/communications/inbox", GetInboxAsync)
    .RequireAuthorization();

It returns the user's 50 most recent communications, newest first, from the records the delivery reports built. The inbox matches records against the sub claim on the user's token, which is the same identity id Ordering dispatched in Part 3, so no new mapping is needed.

Authentication follows eShop's existing pattern. Identity gets a communications scope, the web app requests it when the user signs in, and Communications validates tokens with eShop's shared AddDefaultAuthentication(). The web app's HTTP client for Communications attaches the user's token:

builder.Services.AddHttpClient<InboxService>(o => o.BaseAddress = new("https+http://communications-api"))
    .AddAuthToken();

The web app adds a Messages page to the account menu, next to My orders. Here's what alice and bob each see after placing an order:

alice
Sent                Channel   Message                                    Status
10/2/2026 8:17 PM   Email     Thanks for your order #11                  Dispatched
                              Order created

bob
Sent                Channel   Message                                    Status
10/2/2026 8:18 PM   SMS       We've received your eShop order #12. ...   Dispatched
                              Order created

Each of them placed one order and got one message, on different channels, because their verified addresses differ. With Twilio configured, bob's status starts as whatever Twilio returned when it accepted the message (usually queued) and changes as Twilio's callbacks arrive.

The same records could feed other things too. A support tool could show a customer's full delivery history, or an alert could fire when one provider's failure rate climbs. Neither needs anything new from the providers, or from Ordering.

Testing without a provider

None of this needs a real Twilio account to test. The sample's tests post a Twilio-shaped status callback to the real DeliveryReportsController, running in an in-memory test server, at the URL Twilio would be given:

var callbackUrl = new Uri("http://localhost/api/communications/delivery-reports")
    .AddPipelineContext(string.Empty, CommunicationIntents.OrderCreated, null, Id.Channel.Sms(), Id.ChannelProvider.Twilio());

await client.PostAsync(callbackUrl, new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["SmsSid"] = "SM123",
    ["MessageSid"] = "SM123",
    ["SmsStatus"] = "delivered",
    ["MessageStatus"] = "delivered",
    ["AccountSid"] = "ACtest"
}));

The callback comes out the other side as an OnStatusChanged report for SM123, with a Delivered status. Another test records a dispatch followed by an undelivered callback, and checks that both land on the same communication with Twilio's error code kept.

Where we ended up

Communications now keeps a record of everything it sends, and of everything providers tell it afterwards:

Ordering
    |
    | OrderCreated
    v
Communications
    |
    +-- compose and dispatch          (Parts 2-4)
    |
    +-- delivery reports
    |       at dispatch               simulator, Twilio, ...
    |       from webhooks             Twilio status callbacks
    |
    +-- one handler -> queue -> recorder -> communicationsdb
    |
    v
Inbox API -> WebApp Messages page

Because DeliveryReport is provider-agnostic, the recording, the inbox, and anything else built on delivery history work the same for every provider. When one provider's specifics matter, its details are still there.

Adding a provider doesn't change any of it. A new provider's package brings its own request adaptor, and its callbacks start landing in the same tables.

Looking back

This series started with a line most applications have somewhere:

await emailClient.SendAsync(...);

The usual next step is to inject that client into the service that knows something happened. That holds up for a while. Then the service learns how to find the customer's email address, then what to put in the message, then which template to use. When SMS arrives, it learns about phone numbers and a second provider SDK. When someone asks whether the message actually arrived, it learns about webhooks. Each step is reasonable. Together they turn a business service into a communications service that happens to manage orders.

eShop never went down that road. Ordering states one intent when an order is created, names the buyer by identity, and hands over the order facts it already has. Its code last changed in Part 3, when it started sending an identity reference and the order's items. Everything after that (two more channels, a different channel for each buyer, delivery tracking from any provider, and an inbox) happened without touching Ordering.

The first thing Transmitly gave us was a stable seam. Application code talks to ICommunicationsClient and an intent name, and that's all. Whether the pipeline runs in the same process or behind a Communications service is a middleware decision, and so is waiting for a database commit before anything goes out. Ordering didn't have to know about either.

Behind that seam, each concern could live with the data it needs. Recipients are resolved through Identity, which owns them, instead of being copied into every service that sends something. Product details come from Catalog at composition time rather than being dragged through Ordering. And because a content model built for communicating sits between the business facts and the templates, email, SMS, and push each use it differently without anyone reassembling the data.

Delivery decisions moved out of business code. A buyer's verified addresses decide which channels can reach them, the pipeline's delivery strategy decides whether they get one message or several, and a provider registration decides which company carries each channel. Swapping SMTP for SendGrid, or the simulator for Twilio, leaves the pipeline and every dispatching service alone.

We also got to see what happened after the send. Reports from the simulator and from Twilio arrive in one provider-agnostic shape, so the recording and the inbox were written once, and provider details like Twilio's error code are still available when they matter.

None of it needed a provider account to build. The simulator ran the whole pipeline, and the tests composed real messages through the real templates and enrichers without touching the network.

Shaped around eShop

None of that required eShop to reorganize itself around a library. Look at the pieces we wrote:

IdentityServerCustomerIdentityResolver   IPlatformIdentityResolver
PushRegistrationProfileEnricher          IPlatformIdentityProfileEnricher
CatalogContentModelEnricher              IContentModelEnricher
EshopCommunicationsMiddleware            ICommunicationClientMiddleware
TransactionalCommunicationsMiddleware    ICommunicationClientMiddleware

Each one adapts Transmitly to something eShop already had. Buyers stayed in Identity, behind an endpoint Identity owns and a service token Identity issues. Product data stayed behind Catalog's existing batch endpoint. The commit deferral hooks into Ordering's own TransactionBehavior. Forwarding uses Aspire's service discovery and eShop's shared service defaults. Transmitly supplied the extension points, and eShop decided what went in them.

That's the right way round. A communications library that dictates where identities live, how transactions work, or how services talk to each other forces its way of working onto every system it touches. Transmitly asks for an implementation of a small interface at the point it needs one.

The built-in pieces work the same way, so when something isn't in the box, it can be added without changing Transmitly:

A channel provider is a dispatcher registered against the channels it supports. A provider Transmitly doesn't ship, an in-house SMS gateway for example, is an IChannelProviderDispatcher<T> and a registration.
Provider webhooks come in through IChannelProviderDeliveryReportRequestAdaptor, the same interface Twilio's adaptor implements in this article.
Template engines implement ITemplateEngine, which is how the Fluid and Scriban integrations work.
Delivery strategies derive from BasePipelineDeliveryStrategyProvider, for when first match and any match don't describe your policy.
Channels implement IChannel, for a medium beyond email, SMS, push, and voice.

The packaged providers and integrations are small, separate repositories, which makes them good references for writing your own.

There's a lot more in Transmitly

The series used a fraction of what Transmitly does. A few of the pieces we didn't get to:

Our templates were C# methods that built strings. Transmitly has pluggable template engines, with Fluid and Scriban integrations, so content can live in templates instead of code.
Beyond SMTP, Twilio, and Firebase there are SendGrid and Mailgun for email, and Infobip for email, SMS, and voice. Voice is a channel in its own right, supported by Twilio and Infobip.
Personas define audience segments as conditions over the recipient profile with AddPersona, and a pipeline can apply only to the segments it names with AddPersonaFilter. They're a natural next step from this article's verified addresses.
A dispatch can name the channels a recipient has chosen, and Transmitly will only deliver on those. Part 2's contract already carries them as AllowedChannels.
We used client middleware to forward dispatches and to wait for a commit. Dispatch middleware runs around each channel dispatch inside the pipeline, which makes it a good home for concerns like auditing.
Delivery report handlers can filter on specific events, channels, providers, or intents, instead of receiving every report like ours did.

The best place to go from here is the repository: github.com/transmitly/transmitly. It has the list of channel providers and integrations, the samples, including this series and smaller starting points like Hello Transmitly and the Microservices sample, and the wiki.

If you try it and something is confusing, missing, or more ceremony than it's worth, I want to hear about it in GitHub Discussions.

Part 4: One Intent, Many Channels and Providers

Jeremy — Wed, 21 Oct 2026 23:00:00 +0000

Part 3 built the content. Ordering dispatches OrderCreated with the order facts it owns, Communications resolves the buyer through Identity, a Catalog enricher fills in product details, and one enriched context comes out the other side. Then a single channel used it: email.

Part 3 also sketched what SMS and push could do with the same context. This article builds them. Along the way we'll separate two ideas that are easy to blur together, channels and providers, and see what it would take to connect real ones like SMTP, Twilio, and Firebase.

The code stays on Transmitly's simulator the whole time. Nothing in this article needs an account, an API key, or a phone.

Ordering doesn't change

Ordering still dispatches exactly what it dispatched in Part 3:

await _communicationsClient.DispatchAsync(
    CommunicationIntents.OrderCreated,
    [buyer],
    TransactionModel.Create(model),
    cancellationToken: cancellationToken);

There's no channels argument, no SMS flag, no push token. Comparing Ordering.API between the Part 3 and Part 4 code turns up no differences at all.

Ordering said an order was created. Whether that becomes one message or three is a communication decision, so every change in this article happens inside Communications.

Every channel needs an address

A channel can only deliver if the recipient has an address it understands. Email needs an email address, SMS needs a phone number, and push needs a device token.

Transmitly handles the matching. When it plans a dispatch, it asks each channel in the pipeline which of the recipient's addresses it can use. The email channel accepts email addresses. The SMS channel accepts phone numbers, and an address type can say which kind of phone it is, so a mobile number gets the text and a home phone doesn't. The push channel accepts device tokens and topics. A channel with no usable address is skipped for that recipient.

So adding channels starts with the recipient profile. Here's what eShop's buyer looks like after identity resolution:

Buyer: alice

Email
    AliceSmith@email.com

Phone
    +11234567890

Identity already owns the email address and the phone number, and the resolver from Part 3 returns both. SMS has what it needs.

Push doesn't. There's no device token anywhere in eShop, and no service in the application that would own one.

Push tokens are communications data

A device token doesn't say who the buyer is. It says where a notification can be delivered, it changes whenever the app is reinstalled, and nothing outside communications has any use for it. That makes it communications data, and Communications should own it.

In Part 3 we noted that the pipeline has a stage for exactly this kind of thing, and that eShop didn't need it yet:

Identity resolution
    |
    v
Identity-profile enrichment     <-- push tokens go here
    |
    v
Content enrichment

Profile enrichers run after resolution and before content is built. They can add to the recipient's profile, which is where channels look for addresses. So Communications gets a small store of push registrations, and a profile enricher that reads from it:

public sealed class PushRegistrationProfileEnricher(IPushRegistrationStore registrations)
    : IPlatformIdentityProfileEnricher
{
    public async Task EnrichIdentityProfileAsync(IPlatformIdentityProfile identityProfile)
    {
        if (identityProfile is not CustomerIdentityProfile customer)
        {
            return;
        }

        foreach (var token in await registrations.GetDeviceTokensAsync(customer.Id))
        {
            customer.AddAddress(new PlatformIdentityAddress(
                token,
                type: PlatformIdentityAddress.Types.DeviceToken()));
        }
    }
}

In Part 3, CustomerIdentityProfile was an immutable record. It's now a class with an AddAddress method, so enrichers like this one can add addresses that Identity doesn't own.

The enricher is registered for the same identity type as the resolver:

.AddPlatformIdentityResolver<IdentityServerCustomerIdentityResolver>(CommunicationIdentityTypes.Buyer)
.AddPlatformIdentityProfileEnricher<PushRegistrationProfileEnricher>(CommunicationIdentityTypes.Buyer)

One gap remains. eShop's apps don't register for push notifications, so there's nothing to put in the store. The sample registers a SimulatedPushRegistrationStore that gives every buyer one simulated device:

public Task<IReadOnlyCollection<string>> GetDeviceTokensAsync(string identityId, CancellationToken cancellationToken = default) =>
    Task.FromResult<IReadOnlyCollection<string>>([$"simulated-device-{identityId}"]);

In a real system, the mobile app would send its token to Communications when the user signs in, and the store would hold whatever devices are registered. The enricher wouldn't change.

After enrichment the profile has an address for every channel:

Buyer: alice

Email
    AliceSmith@email.com

Phone
    +11234567890

Device token
    simulated-device-…

One context, three renderings

With addresses in place, the pipeline in the Communications service's Program.cs adds two channels next to the email:

.AddPipeline(CommunicationIntents.OrderCreated, pipeline =>
{
    pipeline.UseAnyMatchPipelineDeliveryStrategy();

    pipeline.AddEmail(
        "orders@eshop.local".AsIdentityAddress("eShop"),
        email =>
        {
            email.AddChannelProviderFilter(EshopChannelProviders.Email);
            email.Subject.AddTemplateResolver(context => OrderCreatedEmail.Subject(context));
            email.TextBody.AddTemplateResolver(context => OrderCreatedEmail.TextBody(context, webAppUrl));
        });

    pipeline.AddSms(
        "+15555550100".AsIdentityAddress("eShop"),
        sms =>
        {
            sms.AddChannelProviderFilter(EshopChannelProviders.Sms);
            sms.Message.AddTemplateResolver(context => OrderCreatedSms.Message(context, webAppUrl));
        });

    pipeline.AddPushNotification(push =>
    {
        push.AddChannelProviderFilter(EshopChannelProviders.Push);
        push.Title.AddTemplateResolver(context => OrderCreatedPush.Title(context));
        push.Body.AddTemplateResolver(context => OrderCreatedPush.Body(context));
        push.AddData(OrderCreatedPush.ActionKey, OrderCreatedPush.OpenOrderAction);
        push.AddDataIfNotNull(OrderCreatedPush.OrderIdKey, context => OrderCreatedPush.OrderId(context));
    });
});

We'll come back to the first line and the provider filters. For now, look at what each channel renders.

All three read the same OrderCreatedContentModel that Part 3's Catalog enricher built. That enricher is registered per recipient, not per channel, so it runs once and every channel shares its result. Adding SMS and push didn't add any calls to Catalog.

The email renders exactly as it did in Part 3. Its "view your order" link now comes from a small OrderLinks helper that the SMS shares. The SMS keeps only what fits in a text message:

public static Task<string?> Message(IDispatchCommunicationContext context, Uri? webAppUrl)
{
    var order = OrderCreatedContentModel.From(context.ContentModel);
    var message = order is null
        ? "We've received your eShop order."
        : $"We've received your eShop order #{order.OrderId}.";

    return Task.FromResult<string?>(OrderLinks.Orders(webAppUrl) is { } ordersLink
        ? $"{message}\nView your order: {ordersLink}"
        : message);
}

which renders as:

We've received your eShop order #123.
View your order: https://eshop.example/user/orders

Every template method returns Task<string?>, which is what AddTemplateResolver takes, so each registration is a single line. A template that later needs to await something can do it without changing how it's registered.

Push is shorter still. The visible part is a title and a sentence. The useful part is the data: an action and an order id the app can use to open the right screen.

Title
    Thanks for your order

Body
    Order #123 has been received.

Data
    action:  open-order
    orderId: 123

That's three quite different messages from one content model, and none of the templates had to fetch anything.

Deciding which channels to use

Now the first line of the pipeline:

pipeline.UseAnyMatchPipelineDeliveryStrategy();

A pipeline with several channels needs a rule for using them, and it helps to know what happens without that line first.

By default, Transmitly walks the channels in the order they were added and delivers on the first one that can reach the recipient. If delivery on that channel fails, it moves on to the next. For our pipeline, that means the buyer gets the email, and SMS and push only come into play if the email can't be delivered:

Default (first match)

OrderCreated
    |
    +-- Email  reachable? deliver and stop
    |
    +-- SMS    otherwise, try this
    |
    +-- Push   last resort

That gives one message per order with a fallback built in, which is usually what you want for an order confirmation. Reordering the channels changes the ladder: put push first and app users get a notification, while everyone else falls through to email.

Transmitly calls this rule a delivery strategy, and a pipeline can pick a different one. This sample opts into any match, which sends on every channel the recipient can be reached on, so we can watch all three channels go out:

Any match

OrderCreated
    |
    +-- Email  -> delivered
    +-- SMS    -> delivered
    +-- Push   -> delivered

Either way, the choice is one line in Communications, and Ordering doesn't know which one is in use. A future policy could go further and respect each recipient's channel preferences. Part 2's dispatch contract already carries AllowedChannels for that.

Channels and providers are different things

So far "SMS" has meant two things at once: the kind of message, and whoever delivers it. Transmitly keeps those apart.

A channel is the medium: email, SMS, push. Channels own content. They know a subject line from a message body, and what an address has to look like.

A channel provider is whoever actually delivers it: an SMTP server, SendGrid, Twilio, Firebase. Providers own transport. They know about API keys, endpoints, and rate limits.

          Channels                    Providers
     (what we send)              (who delivers it)

   Email  ---------------------->  SMTP / SendGrid
   SMS    ---------------------->  Twilio
   Push   ---------------------->  Firebase

The pipeline is written entirely in terms of channels. Providers are registered separately, once, and the two meet only at dispatch time.

In this sample, all three providers are simulators:

public static class EshopChannelProviders
{
    public static string Email { get; } = Id.ChannelProvider.Simulation("Email");
    public static string Sms { get; } = Id.ChannelProvider.Simulation("Sms");
    public static string Push { get; } = Id.ChannelProvider.Simulation("Push");

    public static CommunicationsClientBuilder AddEshopChannelProviders(this CommunicationsClientBuilder builder) =>
        builder
            .AddSimulationSupport(providerId: "Email")
            .AddSimulationSupport(providerId: "Sms")
            .AddSimulationSupport(providerId: "Push");
}

Each simulator stands in for the real provider that would sit behind its channel. That's what the AddChannelProviderFilter calls in the pipeline are for: each channel names the one provider it should use.

Real providers declare the channels they support, so a Twilio registration would never be offered an email. A simulator accepts any channel. Without the filters, any match would send each message through all three simulators, and the buyer would get three emails, three texts, and three pushes. Naming each channel's provider keeps the routing explicit and keeps the simulated setup shaped like the real one.

Connecting real providers

To send real messages, you change the provider registrations. The pipeline stays as it is, and so do the templates, the enrichers, and everything outside Communications.

Each provider is a package:

Transmitly.ChannelProvider.Smtp
Transmitly.ChannelProvider.Twilio
Transmitly.ChannelProvider.Firebase

and each replaces one simulator registration, with its credentials coming from configuration:

public static CommunicationsClientBuilder AddEshopChannelProviders(
    this CommunicationsClientBuilder builder,
    IConfiguration configuration) =>
    builder
        .AddSmtpSupport(smtp =>
        {
            smtp.Host = configuration["Smtp:Host"];
            smtp.Port = 587;
            smtp.UserName = configuration["Smtp:UserName"];
            smtp.Password = configuration["Smtp:Password"];
        })
        .AddTwilioSupport(twilio =>
        {
            twilio.AccountSid = configuration["Twilio:AccountSid"];
            twilio.AuthToken = configuration["Twilio:AuthToken"];
        })
        .AddFirebaseSupport(firebase =>
        {
            firebase.ProjectId = configuration["Firebase:ProjectId"];
            firebase.Credential = FirebaseCredential.GetApplicationDefault();
        });

The provider ids the channels pin to change with them:

public static string Email { get; } = Id.ChannelProvider.Smtp();
public static string Sms { get; } = Id.ChannelProvider.Twilio();
public static string Push { get; } = Id.ChannelProvider.Firebase();

That's the whole code change. The rest is operational: an SMTP server or a SendGrid account, a Twilio number to replace the placeholder +15555550100 the SMS is sent from, a Firebase project, and a push registration store that real devices write to.

Swapping one provider for another works the same way. Moving email from SMTP to SendGrid replaces AddSmtpSupport with AddSendGridSupport and changes one id.

Providers can also be combined. With first-match delivery, a channel that has two providers gets a fallback for free: if the first provider fails, Transmitly tries the next before moving on to the next channel. A team could run SendGrid for email and keep SMTP behind it for the day SendGrid has an outage.

None of these choices reach the services that dispatch intents. Ordering didn't change when we added channels, and it wouldn't change if every provider changed tomorrow.

Why stay on the simulator?

It's tempting to wire up a real provider as soon as possible. There's a good case for not doing it in the sample, and for keeping the simulator around even after real providers exist.

The simulator runs the whole pipeline. Identity resolution, both enrichers, every template, and the channel and provider selection all happen exactly as they would in production. Only the last step, handing the message to an external service, is simulated.

It also reports what it would have sent. Every simulated delivery raises a delivery report with the channel, the provider, and the full rendered communication. The Communications service logs those reports, so placing an order in the web app produces three entries in the communications-api logs in the Aspire dashboard:

[Email:Simulation.Email:Dispatched] ...
[Sms:Simulation.Sms:Dispatched] ...
[Push:Simulation.Push:Dispatched] ...

each followed by the rendered message.

And it makes the composition testable. The sample's tests register the same OrderCreated pipeline as Program.cs, with the real resolver, enrichers, and templates and fake Identity and Catalog services behind them. They dispatch an order and check all three rendered messages, including which provider each one went through, without touching the network.

Where we ended up

The OrderCreated intent now reaches the buyer three ways:

Ordering
    |
    | OrderCreated
    | order model + buyer reference
    v
Communications
    |
    +-- resolve buyer             Identity
    +-- add push devices          push registration store
    +-- enrich products           Catalog
    |
    v
Enriched content context
    |
    +-- Email  -> Simulation.Email   (SMTP, SendGrid)
    |
    +-- SMS    -> Simulation.Sms     (Twilio)
    |
    +-- Push   -> Simulation.Push    (Firebase)

Ordering's code is identical to Part 3's. Everything new lives in Communications:

Recipient addresses
    resolver and profile enrichers

Channel content
    templates per channel

Channel policy
    delivery strategy

Delivery
    providers, one per channel

Each of those can change on its own schedule: a new channel is a pipeline change, a new policy a strategy change, a new provider a registration change. The intent stays OrderCreated through all of it.

One word in those log lines deserves a second look: Dispatched. With the simulator, handing a message to the provider and the message arriving are the same moment. Real providers rarely work that way. Twilio or SendGrid accept the message, queue it, and report back later as it's sent, delivered, bounced, or opened, and those later reports are worth keeping.

In the next article, we'll explore how delivery updates from any provider land in one place, with Twilio as the example, and buyers get an inbox of everything we've sent them.

Part 3: Composing the Message Where the Data Lives

Jeremy — Tue, 20 Oct 2026 23:00:00 +0000

Part 2 built the path. Ordering dispatches an OrderCreated intent to the buyer's email address through Transmitly, holds it until the order commits, and middleware forwards the communication context to the Communications service, where the configured pipeline decides how to fulfill it.

That first pipeline produced a deliberately bare email:

Subject:
Thanks for your order!

Body:
We've received your order and we'll let you know when it ships.

It was enough to prove the boundary, but a customer wouldn't get much out of it.

A good order confirmation might include the customer's name, the items in the order, the amount paid, and product details. Some of that is already in hand when Ordering dispatches. The rest belongs to other services.

Part 1 gave that assembly job to Communications: Ordering supplies the identifiers and facts it owns, and Communications assembles the communication model. This article builds that step, starting with the recipient. More channels, and the policy for choosing among them, come in Part 4.

Transmitly treats the model supplied at dispatch as input to composition. Before content reaches a template, the pipeline can resolve platform identities, enrich those identity profiles, and enrich the content model itself.

At a high level, the lifecycle looks like this:

DispatchAsync(...)
  |
  +-- (optional) Resolve identity references
  |       |
  |       v
  |   IPlatformIdentityProfile[]
  |
  +-- Run PlatformIdentityProfile enrichers
  |
  +-- Build dispatch/content context
  |
  +-- Run ContentModel enrichers
  |       by scope and order
  |
  +-- Render channel content
  |
  +-- Dispatch channels/providers

Starting with the transactional model

When an order is created, Ordering has just built the Order aggregate. eShop's aggregate holds its order items, and each OrderItem keeps the catalog product identifier, product name, unit price, discount, picture URL, and quantity. The order can calculate its total from those stored values.

So the order itself is a natural source for the initial transactional model.

We project the communication-relevant data into OrderCreatedModel:

public sealed record OrderCreatedModel(
    int OrderId,
    DateTime OrderDate,
    IReadOnlyCollection<OrderCreatedItem> Items,
    decimal Total);

public sealed record OrderCreatedItem(
    int ProductId,
    string ProductName,
    int Quantity,
    decimal UnitPrice);

Then Ordering dispatches with the model it already has:

await communicationsClient.DispatchAsync(
    CommunicationIntents.OrderCreated,
    [buyer],
    TransactionModel.Create(new OrderCreatedModel(
        order.Id,
        order.OrderDate,
        order.OrderItems
            .Select(item => new OrderCreatedItem(
                item.ProductId,
                item.ProductName,
                item.Units,
                item.UnitPrice))
            .ToArray(),
        order.GetTotal())));

That gives Communications a solid starting point without making the originating service build the final communication.

There are two models in play from here on. The transactional model is the context supplied at dispatch. The content model used for rendering keeps developing as that context moves through Communications.

Ordering
    |
    | OrderCreated
    | + transactional model
    | + recipient identity
    v
Communications
    |
    | composition
    v
Enriched content context
    |
    v
Channel-specific rendering

How much belongs in that initial model depends on the communication.

When should data enter the communication?

Data can enter composition at a few different points.

An originating service can supply most of the model at dispatch. That works well when the service already loaded the relevant state for the business operation. OrderCreated fits: Ordering already knows which products were bought, how many, and at what price.

Another communication might arrive mostly as references and lean on resolution during composition. If Communications needs data owned by another bounded context, passing a stable identifier is usually better than copying that domain's data through the originating service.

And sometimes the right model is assembled later. A communication may be delayed, accumulated with related ones, or enriched with information that changes between the business operation and rendering. Part 1's five-orders summary is that case.

These choices sit on a spectrum:

More data supplied at dispatch
<---------------------------------------------->

More data resolved during composition

There's no prize for pushing every communication to one end.

For eShop we'll stay near the simple end. Ordering supplies the order information it already has, and Communications does two pieces of cross-service composition:

Buyer identity
      |
      v
Identity resolution

Product identifiers
      |
      v
Catalog enrichment

Both use domains eShop already has, which makes them a good way to exercise Transmitly's enrichment workflow.

Resolving the recipient

Ordering identifies the buyer because the order belongs to someone. How to reach that person is a different concern.

In Part 2, Ordering handed Communications an email address taken from the buyer's access token. That worked, but it meant Ordering was supplying an address. Once SMS and push arrive, the same approach would have Ordering supplying phone numbers and device tokens too, and address management would leak into the ordering domain.

Communications can resolve the identity itself, so Ordering never has to know how a buyer is reached. The value passed to DispatchAsync() becomes an identity reference built from the identifier Ordering already owns:

var buyer = new IdentityReference(CommunicationIdentityTypes.Buyer, domainEvent.UserId);

Ordering no longer reads the email claim at all, and GetUserEmail() is gone from its identity service.

When Communications processes the dispatch, Transmitly resolves that reference into one or more IPlatformIdentityProfile instances. Resolvers are registered by identity type:

builder.Services.AddTransmitly(tly => tly
    // ...
    .AddPlatformIdentityResolver<IdentityServerCustomerIdentityResolver>(CommunicationIdentityTypes.Buyer)
    // ...
);

Transmitly only runs a resolver whose type matches the reference, which is why Buyer is a shared constant rather than a string typed in two services. eShop's resolver asks the service that owns the data. It gets a client-credentials token from Identity and calls a new POST /api/identities/resolve endpoint, which returns the buyer's name along with the email address and phone number on the account, each marked as verified or not. On the Identity side, Config.cs adds a communications client that may request the IdentityServerApi scope, and the endpoint only accepts tokens carrying that scope.

Conceptually:

buyer-123
    |
    v
Identity resolution
    |
    v
IPlatformIdentityProfile
    |
    +-- Name
    |
    +-- Email address
    |
    +-- SMS address
    |
    +-- Other identities

Today's email only needs the name and the email address. The rest matters once other channels show up, and Ordering keeps sending the same identity reference while that happens.

Enriching the identity profile

Resolution gives us the initial IPlatformIdentityProfile. Profile enrichers run next, before the content itself is built.

A profile might start with very little:

Platform identity
    buyer-123

Email
    ava@example.com

An enricher could then add recipient-oriented information:

Name
    Ava Rodriguez

Locale
    en-US

Time zone
    America/Denver

Communication preferences
    Email: enabled
    SMS: enabled

Sources will differ between applications. Some systems get almost all of this during identity resolution. Others keep customer profiles, preference stores, tenant configuration, or communication-specific data somewhere else.

These enrichers work on the recipient. They establish who the recipient is in communications terms, how to reach them, and which recipient-specific details should feed later decisions. This is the locale and preferences row from Part 1's composition model.

eShop is the first kind of system. Identity resolution already returns the buyer's name and the addresses Identity holds for the account, which is everything today's email needs, and eShop has no locale or preference store to draw from. So our pipeline doesn't register a profile enricher yet. Part 4 uses this stage for push device tokens, which Identity doesn't have.

Once profiles are resolved and enriched, Transmitly builds the content context for the pipeline.

Enriching the transactional content

Content-model enrichment deals with the subject of the communication.

Our transactional model already has the order facts Ordering supplied:

Order
    OrderId
    OrderDate
    Total

Items
    ProductId
    ProductName
    Quantity
    UnitPrice

The ProductId values give us a natural link to eShop's Catalog service.

Catalog exposes a batch endpoint that returns several items by identifier, which is handy, since an order can contain many products.

A content-model enricher can collect those identifiers:

var productIds = order.Items
    .Select(x => x.ProductId)
    .Distinct()
    .ToArray();

and fetch their Catalog representations in one call:

GET /api/catalog/items/by
    ?ids=1
    &ids=2
    &ids=3

Catalog contributes each product's description, a route to its picture, and its brand and type. The batch endpoint returns brand and type as identifiers, so the enricher also reads Catalog's brand and type lists to get their names.

If Catalog can't be reached, the enricher logs a warning and the email goes out without product details. The order facts still come from Ordering.

The enricher extends each item from:

ProductId
ProductName
Quantity
PurchasedUnitPrice

to:

ProductId
ProductName
Quantity
PurchasedUnitPrice
Brand
ProductType
Description
ProductImage

The model gets richer without Ordering taking responsibility for Catalog's representation.

Transactional facts and enrichment data

Bringing in Catalog data raises a semantic question. The price stored on the order and the current Catalog price can both exist, and they mean different things.

Say the customer bought an item for:

$29.99

and Catalog now lists it for:

$34.99

The order confirmation should show what the customer actually paid. eShop's OrderItem keeps the unit price from when the item was added to the order, alongside its product identifier and other transactional values. The enricher copies that price into PurchasedUnitPrice and never reads Catalog's.

Catalog adds context without redefining the transaction. That suggests a rule for enrichment:

An enricher should understand the semantics of the model it is enriching. Current data can supplement transactional data, refresh it when the communication requires current state, or participate in a new derived representation.

Which behavior fits depends on the communication. For OrderCreated, the purchased quantity and price describe the transaction, and current Catalog data layers richer product presentation on top. Another pipeline might need something quite different.

From dispatch to composed content

With identity resolution and Catalog enrichment in place, the full composition path looks like this:

Ordering
    |
    | DispatchAsync("OrderCreated", ...)
    |
    | Transactional model
    |   OrderId
    |   OrderDate
    |   Items
    |       ProductId
    |       ProductName
    |       Quantity
    |       UnitPrice
    |   Total
    |
    | Recipient
    |   BuyerIdentityId
    v
Communications
    |
    v
Resolve BuyerIdentityId
    |
    v
IPlatformIdentityProfile[]
    |
    v
PlatformIdentityProfile enrichers
    (none needed for eShop yet)
    |
    v
Build dispatch/content context
    |
    v
ContentModel enrichers
    |
    +-- Batch resolve ProductIds from Catalog
    |
    +-- Add product presentation data
    |
    v
Enriched OrderCreated content context
    |
    v
Render channel content

The application supplied an intent, a recipient reference, and some transactional context. The pipeline turned those into a model built for communication.

A purpose-built content model

By the time rendering starts, the content context holds information from several sources:

public sealed record OrderCreatedContentModel(
    RecipientModel Recipient,
    int OrderId,
    DateTime OrderDate,
    decimal Total,
    IReadOnlyCollection<OrderCreatedContentItem> Items);

public sealed record RecipientModel(
    string? FirstName);

public sealed record OrderCreatedContentItem(
    int ProductId,
    string ProductName,
    int Quantity,
    decimal PurchasedUnitPrice,
    string? Brand,
    string? ProductType,
    string? Description,
    string? ProductImage);

Broken down by where each piece came from:

Ordering
    OrderId
    OrderDate
    ProductName
    Quantity
    PurchasedUnitPrice
    Total

Identity
    FirstName
    communication addresses

Catalog
    Brand
    ProductType
    Description
    product presentation data

Neither the template nor the channel provider has to reconstruct that composition. Data spread across the application has already been turned into one communication context.

Why make enrichment part of the pipeline?

We could do all of this before calling Transmitly. Ordering could resolve the customer, call Catalog, build a large content model, pick an address, and submit a finished message.

That's the leak Part 1 described. Ordering slowly turns into an orchestrator for data that exists mostly to produce communications, just because it happened to create the intent.

Transmitly gives that composition an explicit lifecycle instead:

Dispatch
   |
   v
Identity resolution
   |
   v
Identity enrichment
   |
   v
Content enrichment
   |
   v
Channel rendering
   |
   v
Delivery

The OrderCreated pipeline can evolve around this lifecycle while Ordering keeps making the same call:

await communicationsClient.DispatchAsync(
    CommunicationIntents.OrderCreated,
    [buyer],
    TransactionModel.Create(model));

A new requirement for product metadata goes in a content enricher. More recipient information comes from an identity-profile enricher. Every channel in the pipeline then reuses the resulting context, and none of that work spreads into the services that create communications.

Enrichers also give us control over timing

So far, the example uses Ordering's transactional model and adds Catalog data. That's the simplest useful implementation, but supplying a model to DispatchAsync() doesn't commit us to rendering those exact values. Composition might happen later.

Imagine an ordering system that lets customers modify an order for a while after placing it. Over a few minutes a customer might:

Place order
    |
Add item
    |
Change quantity
    |
Remove item
    |
Update payment

Turning each of those into a notification produces a stream of messages that's technically accurate and practically annoying.

A communication policy could instead accumulate the related activity for a window, much like Part 1's five-orders summary:

OrderPlaced -------\
ItemAdded ----------\
QuantityChanged -----> accumulated communication
ItemRemoved --------/
PaymentUpdated ----/
                         |
                         | N-minute window
                         v
                  ready to compose

When the accumulated communication is ready, Communications might decide the most useful thing to show is the current order rather than the sequence of models originally supplied.

An order content enricher can take the OrderId, fetch the latest authoritative state, and update the content model before rendering:

Accumulated context
       |
       | OrderId
       v
Order enricher
       |
       v
Current order state
       |
       v
One composed communication

The original dispatch models still mattered. They described the operations that triggered the communication and carried the data available at each point. The communication policy decides what's finally presented.

The general rule:

Dispatch captures the context that caused a communication. Composition determines the information ultimately presented to the recipient.

Sometimes those two models are nearly identical. Sometimes composition adds a few properties. A delayed or accumulated workflow may refresh much more before rendering.

Resolving at composition time is another valid starting point

The same reasoning explains why another application might dispatch a much smaller model from the start.

Instead of:

OrderCreated
    OrderId
    OrderDate
    Items
    Total

it could send:

OrderCreated
    OrderId

and let an order enricher resolve the full state later.

That can make sense when the source domain exposes a stable historical representation, when communications are routinely delayed, or when current state matters more than saving a lookup.

Our eShop implementation doesn't need that. The order is already in hand when it's created, so passing a useful transactional model keeps the example direct. The architecture leaves the choice open for intents that need different semantics.

Direct calls versus local projections

The Catalog enricher can start with the simplest data access: call Catalog during composition.

ContentModel enricher
       |
       v
Catalog API
       |
       v
Catalog items

For this example's volume and purpose, that's enough.

A larger communications system might get enricher data differently. Communications could keep a local projection fed by Catalog integration events:

Catalog
    |
    | integration events
    v
Communications product projection
    |
    v
Catalog enricher

From the pipeline's point of view, the enrichment stage doesn't change. Only the enricher's data source does.

Recipient profiles can evolve the same way. A platform identity resolver might call an identity service directly at first, then later resolve from communications-owned data synchronized from that service.

The architecture can grow when latency, availability, or throughput actually call for it. The first implementation doesn't need any of those mechanisms.

Rendering comes last

Once identity resolution and enrichment finish, the Communications service has one shared context that each channel can use to express the intent. This is where keeping the communication intent separate from the channel content pays off.

Our intent is still:

OrderCreated

The enriched content model contains:

OrderCreatedContentModel

Recipient
    FirstName

Order
    OrderId
    OrderDate
    Total

Items
    ProductName
    Quantity
    PurchasedUnitPrice
    Brand
    ProductType
    Description
    ProductImage

The recipient's addresses aren't in it. They stay on the resolved identity profile, which is where each channel looks for an address it can use.

Email has room to show most of the content model directly. The code-defined email template renders a summary of the order. If alice, one of eShop's seeded buyers, orders two pairs of hiking boots and a climbing harness, she gets:

Subject:
Thanks for your order #123

Hi Alice,

We've received your order. We'll let you know when it ships.

2 × Wanderer Black Hiking Boots
    Daybird
    $109.99 each

1 × Summit Pro Harness
    Gravitator
    $89.99

Order total: $309.97

View your order:
https://eshop.example/user/orders

eShop has no page for a single order, so the link goes to the buyer's order list. The other channels come in Part 4, but here's how differently they'll use the same context.

SMS has different constraints. Repeating the full email would waste the channel, so the same OrderCreated pipeline can define a much shorter SMS:

We've received your eShop order #123.
View your order: https://eshop.example/user/orders

Push can be shorter still, because the notification itself can open the app. The visible part is a title and a sentence, and the data tells the app which order to show:

Title:
Thanks for your order

Body:
Order #123 has been received.

Data:
action:  open-order
orderId: 123

All three express the same communication:

                         OrderCreated
                              |
                    enriched content context
                              |
              +---------------+---------------+
              |               |               |
              v               v               v
            Email            SMS             Push
              |               |               |
       detailed summary    short link      brief alert
       and order link      to order        + app action

Ordering didn't have to make any of those choices.

Communications knows things Ordering doesn't need to reason about: which addresses the recipient profile has, which channels the recipient has enabled, how much content suits each medium, whether a channel can link into the app, and which providers are configured to deliver it. Those factors shape the communication strategy independently of the intent.

For one customer, OrderCreated might mean email only:

OrderCreated
    |
    +-- Email

Another might prefer SMS:

OrderCreated
    |
    +-- SMS

A mobile-app user might get push immediately and a richer email for reference:

OrderCreated
    |
    +-- Push
    |
    +-- Email

The content differs by channel, and the enriched context underneath is shared.

So Ordering doesn't dispatch OrderCreatedEmail, OrderCreatedSms, or OrderCreatedPush, the kind of channel-bound name Part 1 warned against. (Those names do show up as template classes inside Communications, starting with this part's OrderCreatedEmail, which is where channel-specific names belong.)

It dispatches:

await communicationsClient.DispatchAsync(
    CommunicationIntents.OrderCreated,
    [buyer],
    TransactionModel.Create(model));

Communications decides how OrderCreated is expressed for that recipient under the current policy. For an imperative like the hypothetical PasswordReset from Part 2, the pipeline fixes those choices instead of leaving them to policy. Resolution, enrichment, and rendering work the same way in both cases.

The Communications domain is taking shape

Our OrderCreated implementation now has several stages:

Ordering
    |
    | business operation
    v
OrderCreated intent
    |
    | transactional context
    | recipient reference
    v
Communications
    |
    +-- identity resolution
    |
    +-- identity-profile enrichment (available, unused for now)
    |
    +-- content-model enrichment
    |
    +-- channel-specific rendering
    |
    +-- provider dispatch

Each stage adds information or applies policy at the point where it's useful.

Ordering contributes the context it already has when the order is created. Identity resolution turns the buyer reference into a recipient Communications can address, and for now it also supplies everything the email needs to know about the buyer. Profile enrichers can add recipient information later. The Catalog content enricher uses the product identifiers already on the order to pull presentation data through eShop's existing batch Catalog API.

Every configured channel then gets that context, so email, SMS, push, or anything else can present the same intent in the form that suits it.

Where we ended up

The transactional model passed to DispatchAsync() gave OrderCreated a head start. Ordering already had the order loaded, so we projected the relevant state instead of loading it again somewhere else.

The rest of the model was built inside Communications:

DispatchAsync(...)
       |
       | Order transactional model
       | Buyer identity reference
       v
Resolve identities
       |
       v
IPlatformIdentityProfile[]
       |
       v
Build content context
       |
       v
Catalog ContentModel enricher
       |
       | ProductId -> richer product information
       v
Enriched content context
       |
       +-------- Email template
       |
       +-------- SMS template   (Part 4)
       |
       +-------- Push content   (Part 4)

Other communications can start differently. One might arrive with little more than identifiers and resolve most of its state during composition. A delayed one might refresh before rendering, and a high-volume system might feed its enrichers from local projections. An accumulated one might combine several operations and compose a single message from the latest state.

They all fit the same pipeline, because the transactional model is only an input to composition.

For eShop, Identity and Catalog are enough to show the mechanics without inventing services the application doesn't have. Between them they cover the two main kinds of enrichment: who we're communicating with, and what we're communicating about.

Once that context exists, each channel can use it differently. Today, email gives the detailed order summary. When SMS and push join the pipeline, SMS will link to the buyer's orders and push will carry the data an app needs to open the order.

Next, we'll demonstrate how the same intent goes out as an email, an SMS, and a push notification, with the simulator standing in for SMTP, Twilio, and Firebase.

Part 2: Sending Email Without Choosing Email

Jeremy — Mon, 19 Oct 2026 23:00:00 +0000

Part 1 ended with a plan: add Transmitly to Microsoft eShop, create a new boundary around an order communication, and start with simulated delivery.

This article adds an OrderCreated communication. The first version produces an email, but as we work through each step, we'll see how dealing with intents helps us expand functionality.

The flow is simple:

Ordering [Transmitly]
    |
    | OrderCreated
    v
Communications [Transmitly]
    |
    | communication policy
    v
Email

Transmitly provides the abstraction on both sides of this boundary. eShop is distributed today, but the same application code could just as easily run a Transmitly pipeline locally. Moving communication processing into another service becomes a configuration and middleware concern, not a new programming model.

Expressing the communication from Ordering

eShop already has a well-defined order-creation operation. When a buyer checks out, Ordering creates the order and owns that state, so it has the business context to say an OrderCreated communication intent now exists.

At the application level, we want that call to stay small:

await communicationsClient.DispatchAsync(
    CommunicationIntents.OrderCreated,
    buyerEmail,
    new { orderId = domainEvent.Order.Id },
    cancellationToken: cancellationToken);

What matters here is the vocabulary.

Ordering expresses an intent to communicate with OrderCreated, not a delivery mechanism. The configured pipeline decides what that means operationally.

Ordering makes this call itself, inside SendOrderCreatedCommunicationWhenOrderStartedDomainEventHandler. It handles OrderStartedDomainEvent, the domain event eShop raises when a new order is created. Another handler for the same event, ValidateOrAddBuyerAggregateWhenOrderStartedDomainEventHandler, publishes OrderStatusChangedToSubmittedIntegrationEvent. Communications could subscribe to that integration event and guess that a message is warranted, but as Part 1 argued, that's the wrong way around. The integration event tells other services a fact. The dispatch tells Communications that Ordering has decided there's an intent to communicate, and it's up to Communications to decide how and when to communicate, if at all.

buyerEmail comes from the email claim on the access token that arrives with the create-order request. Ordering reads it for this one call and doesn't store it. That keeps the first slice small, but it's a shortcut, and we'll come back to it.

In a smaller application, the whole pipeline could be registered in the same host (Program.cs):

var communicationsClient = new CommunicationsClientBuilder()
    .AddSimulationSupport()
    .AddPipeline(CommunicationIntents.OrderCreated, pipeline =>
    {
        pipeline.AddEmail(
            "orders@eshop.local".AsIdentityAddress("eShop"),
            email =>
            {
                email.Subject.AddStringTemplate(
                    "Thanks for your order!");

                email.TextBody.AddStringTemplate(
                    "We've received your order and we'll let you know when it ships.");
            });
    })
    .BuildClient();

Calling DispatchAsync() triggers our OrderCreated pipeline, composes the configured email, and hands it to the simulation provider.

When communication requirements are local to one application, that's a perfectly reasonable deployment model.

eShop gives us a reason to go further.

Moving pipeline execution into Communications

Once several services need transactional communications, centralizing composition and delivery starts to pay off.

Ordering may need OrderCreated, OrderShipped, and OrderCancelled. Identity may need PasswordReset. Payment may eventually need PaymentFailed. Over time each of those can pick up templates, localization, recipient preferences, multiple channels, and provider-specific behavior.

Instead of spreading that configuration across every service, we move pipeline configuration and management into a dedicated Communications service.

Even with a whole new service in the picture, our application code still doesn't change. Transmitly's middleware gives us a seam between dispatching an intent and processing it.

The path becomes:

                    Ordering
                       |
                       | DispatchAsync(
                       |   "OrderCreated",
                       |   buyerEmail,
                       |   { orderId })
                       v
                    Transmitly
                       |
                 client middleware
                       |
                       v
              Communications API
                       |
                    Transmitly
                       |
                  OrderCreated
                    pipeline
                       |
                       v
                     Email

The middleware receives the communication context created during dispatch and forwards what the Communications service needs to continue processing it.

Transmitly's Microservices sample uses the same pattern. Application code keeps working through ICommunicationsClient, and middleware decides that processing continues across a service boundary.

Sharing the client configuration

In an app like eShop, several services will probably need the same remote communications capability. Repeating the transport configuration in each project just invites drift, so this is a natural spot for a shared extension.

In an application project, configuration can be as small as:

builder.Services.AddEshopCommunications();

That extension configures Transmitly and registers the middleware that forwards communications to the central service.

Conceptually:

AddEshopCommunications()
        |
        +-- register Transmitly
        |
        +-- add forwarding middleware
        |
        +-- configure Communications endpoint

Ordering, Identity, Payment, and any other service can use the same extension and keep their own communication vocabulary.

Their application code still depends on:

ICommunicationsClient

and dispatches intents the same way:

await communicationsClient.DispatchAsync(
    CommunicationIntents.OrderCreated,
    buyerEmail,
    new { orderId = domainEvent.Order.Id });

Shared code holds the stable intent names used across the transport boundary, not their pipeline definitions. CommunicationIntents publishes the intents available to everyone. Composition, channels, templates, and delivery policy stay with Communications.

This pays off if the deployment architecture changes later. A service could process pipelines locally in one environment and forward them remotely in another.

Waiting for the order to commit

There's a timing problem hiding in that handler. eShop runs domain event handlers before it saves anything: OrderingContext.SaveEntitiesAsync dispatches domain events, then calls SaveChanges, and TransactionBehavior commits the transaction after the command handler returns. Integration events cope with this through eShop's outbox. They're saved inside the transaction and published only after the commit.

A dispatch sent straight from the handler doesn't get that protection. It goes out while the transaction is still open. If the commit then fails, the buyer gets a confirmation for an order that doesn't exist.

The fix uses the same seam as forwarding: client middleware. Ordering registers one more middleware next to the shared setup:

builder.Services.AddEshopCommunications();
builder.Services.AddSingleton<ICommunicationClientMiddleware, TransactionalCommunicationsMiddleware>();

AddEshopCommunications() adds any registered middleware after the forwarding middleware, so it sees each dispatch first. TransactionBehavior opens a scope around each transaction and flushes it once the commit and the integration events are done:

using var pendingCommunications = PendingCommunications.Begin();

// ... begin, handle the command, commit ...

await _orderingIntegrationEventService.PublishEventsThroughEventBusAsync(transactionId);
await pendingCommunications.FlushAsync(_logger, CancellationToken.None);

While the scope is open, the middleware holds each dispatch instead of forwarding it. If the transaction fails, the scope is disposed without a flush and the dispatch is dropped. The handler still calls communicationsClient.DispatchAsync() exactly as before. It doesn't know the dispatch was deferred.

Held dispatches live in memory. If the process stops between the commit and the flush, the communication is lost. A durable outbox for communication intents is possible, but it's outside the scope of this series.

A general dispatch boundary

The Communications service's HTTP surface can follow the same principle.

Every application performs the same operation: dispatch a communication intent along with the context needed to process it.

POST /api/communications/dispatch

The dispatch context carries the intent, the recipients, the transactional model, any dispatch options, and metadata about the dispatch itself. In the shared contract that's CommunicationDispatchRequest:

CommunicationDispatchRequest

    Intent
        OrderCreated

    Recipients
        alice@example.com

    Model
        orderId: 123

    AllowedChannels / PipelineId / Culture
        (empty: the pipeline decides)

    Metadata
        CorrelationId   trace id of the create-order request
        Source          Ordering.API
        DispatchedAt    2026-10-01T16:04:12Z
        Properties      baggage from the current activity

The forwarding middleware fills in the metadata, so application code doesn't pass any of it. The correlation id reuses the current trace id, which lets one dispatch be followed through both services' logs. Properties come from the activity's baggage, so a service can attach ambient context, such as a tenant, without changing the DispatchAsync() call.

When it arrives, the Communications service hands that context back to Transmitly, which resolves the intent against the configured pipeline catalog.

So the transport API stays stable as the catalog grows:

OrderCreated
OrderShipped
OrderCancelled
PasswordReset
PaymentFailed
WelcomeCustomer

Each intent is a different communication policy. They all enter Communications through the same dispatch operation.

That gives the service a clean shape. The HTTP layer transports communication context. Transmitly handles data resolution, composition, and dispatch strategy.

Defining the pipeline catalog

For the first implementation, we define the pipeline directly in code, in the Communications service's Program.cs:

builder.Services.AddTransmitly(tly => tly
    .AddSimulationSupport()
    .AddPipeline(CommunicationIntents.OrderCreated, pipeline =>
    {
        pipeline.AddEmail(
            "orders@eshop.local".AsIdentityAddress("eShop"),
            email =>
            {
                email.Subject.AddStringTemplate(
                    "Thanks for your order!");

                email.TextBody.AddStringTemplate(
                    "We've received your order and we'll let you know when it ships.");
            });
    }));

Looks familiar, doesn't it? It's the same pipeline from the single-host example, now living in Communications. That gives OrderCreated a concrete meaning inside the service.

OrderCreated
     |
     v
   Email
     |
     v
Simulation Provider

Static configuration works well for a sample because the whole policy fits in a few lines of code. It's also enough for plenty of production applications.

More complex systems may eventually want pipeline configuration to come from somewhere else.

A database might hold tenant-specific communication rules. Templates might live in a CMS, and localization in a content service. Or administrators might need to change communication policy without redeploying the Communications service.

Those are all different implementations of the same responsibility:

                    Communications
                          |
                          v
                  Pipeline Resolution
                          |
             +------------+------------+
             |            |            |
             v            v            v
           Code        Database       CMS
             \            |            /
              \           |           /
               +----------+----------+
                          |
                          v
                 Communication Pipeline
                          |
                   +------+------+
                   |      |      |
                 Email   SMS    Push

Transmitly's extensibility leaves the Communications domain room to grow in that direction without touching the services that dispatch intents.

So the real decision isn't where pipeline configuration is stored. It's where responsibility for the pipeline lives.

Why use Transmitly on the client side?

At first glance, the originating service needs very little. We could write an HttpClient, serialize an intent, and post it to /api/communications/dispatch.

For a single application with a fixed distributed architecture, that might be enough.

Transmitly gives us a broader abstraction.

The same application call:

await communicationsClient.DispatchAsync(
    CommunicationIntents.OrderCreated,
    buyerEmail,
    new { orderId = domainEvent.Order.Id });

works in either of these deployments:

Local processing

Application
    |
    v
ICommunicationsClient
    |
    v
Pipeline
    |
    v
Provider

or:

Remote processing

Application
    |
    v
ICommunicationsClient
    |
    v
Forwarding Middleware
    |
    v
Communications Service
    |
    v
Pipeline
    |
    v
Provider

The application is coupled to the communication concept, not to where that communication gets processed.

That matters as a system changes.

An application can start with local SMTP and a handful of pipelines. As communications grow, a shared extension can configure the same client to forward dispatches to a central service. Pipeline definitions then move into Communications, along with templates, recipient resolution, delivery reporting, and channel policy.

The business code that created those intents doesn't have to follow that migration.

That's the practical reason to use Transmitly on both sides. One communications programming model, while middleware, pipeline configuration, and deployment topology evolve around it.

Keeping the communication context meaningful

The generic dispatch endpoint works because the payload is a communication intent, not a prebuilt message.

In this first slice, Ordering supplies the recipient as an email address, along with a model containing information it owns:

OrderCreated

Recipient
    alice@example.com

Model
    orderId: 123

Communications uses that context to build whatever the configured pipeline needs. Today that's one email.

This is the shortcut from earlier. By passing an address, Ordering has taken on a small piece of address management. One email claim from a token is easy to live with. But when SMS arrives, the same buyer also needs a phone number:

+1 555 ...

and push delivery needs one or more device tokens. None of that belongs in Ordering. Ordering knows the buyer as an identity, and knowing how to reach that identity on each channel is Communications' job.

In Part 3, Ordering stops passing an address. It dispatches the buyer's identity, and Communications resolves that identity to the addresses each channel needs. The intent and the model stay the same. The recipient becomes an identity reference instead of an address.

Once recipients are resolved inside Communications, an OrderCreated pipeline can grow from:

OrderCreated
     |
     v
   Email

to:

OrderCreated
     |
     +----> Email
     |
     +----> SMS

without changing anything Ordering sends.

Recipient resolution, channel availability, and communication preferences all become part of the communications model.

Building the first vertical slice

For this article, we keep the first pipeline deliberately small.

Ordering dispatches:

await communicationsClient.DispatchAsync(
    CommunicationIntents.OrderCreated,
    buyerEmail,
    new { orderId = domainEvent.Order.Id });

Once the order commits, Transmitly middleware forwards that communication context to:

POST /api/communications/dispatch

The Communications service resolves:

OrderCreated

and finds the pipeline we configured earlier:

OrderCreated
     |
     v
Email
     |
     v
Simulation

The simulation provider gives us a complete dispatch path without bringing an external provider into the example.

┌────────────────────────────┐
│          Ordering          │
│                            │
│ Order created              │
│      |                     │
│      v                     │
│ Dispatch("OrderCreated")   │
└─────────────┬──────────────┘
              |
              v
    Transmitly Middleware
              |
              v
  /api/communications/dispatch
              |
              v
┌────────────────────────────┐
│       Communications       │
│                            │
│ Pipeline Catalog           │
│      |                     │
│      +-- OrderCreated      │
│              |             │
│              v             │
│            Email           │
│              |             │
│              v             │
│          Simulation        │
└────────────────────────────┘

Once that path works, swapping simulation for SMTP or SendGrid is a provider configuration change inside Communications.

The more interesting change is adding a channel. If Product decides new orders should also send an SMS, the pipeline grows and Ordering keeps dispatching the same OrderCreated intent.

That's where the intent abstraction starts earning its keep.

Adding another service

The design gets clearer once another part of eShop needs communications.

Say Identity needs to send password-reset communications.

PasswordReset isn't part of this series' code. It's here to show how a second service would plug into the same boundary.

Identity would use the same shared setup:

builder.Services.AddEshopCommunications();

and the same application abstraction:

await communicationsClient.DispatchAsync(
    CommunicationIntents.PasswordReset,
    recipient,
    model);

The context would travel through the same dispatch endpoint to the same Communications service.

The catalog would then contain:

OrderCreated
PasswordReset

Each pipeline would have its own composition and channel policy. Both originating services would use the same communication model.

PasswordReset isn't quite like OrderCreated, though. In Part 1's terms it's closer to an imperative. Identity can't let channel policy or customer preferences decide where a reset link goes; it has to reach the verified address on the account. So the PasswordReset pipeline would be locked to that channel and recipient, while OrderCreated stays free to grow. The dispatch call would look the same either way. The difference lives in how Communications configures each pipeline.

As the application grows, the architecture ends up looking like this:

Ordering --------\
                  \
Identity ----------> Communications
                  /        |
Payment ----------/         v
                     Pipeline Catalog
                      /     |      \
                     /      |       \
            OrderCreated PasswordReset ...

The shared code stays small because it defines how to reach Communications, not what Communications knows how to send.

That keeps the catalog centralized without making every application depend on a catalog library.

The communications client and the applications don't have to evolve in lockstep. Developers can dispatch intents before Communications has configured them, and the communications team can wire up templates, channels, and delivery strategy on its own schedule. Until an intent has a pipeline, Transmitly reports the dispatch as Pipeline Not Found and nothing is sent, but nothing breaks either.

Where we ended up

The requirement most applications start with is easy to state:

Send an email when an order is placed.

The implementation gives the application a more durable concept:

OrderCreated

Ordering dispatches that intent through ICommunicationsClient, and Ordering's own middleware holds it until the order commits. Shared Transmitly configuration adds middleware that forwards the communication context to a generic dispatch endpoint. The Communications service resolves OrderCreated against its pipeline catalog and, for now, produces one simulated email.

The design separates three concerns:

Application
    expresses communication intent

Transmitly infrastructure
    determines where it is processed

Communications
    determines how it is composed and delivered

In eShop, processing happens in a dedicated service. A smaller application could use the same Transmitly API with locally configured pipelines. The Communications service defines its catalog in code today. A more advanced implementation could pull pipelines, templates, or other policy from a database, a CMS, or some other configuration system.

Those choices can change independently because the business-facing abstraction stays the same:

await communicationsClient.DispatchAsync(
    CommunicationIntents.OrderCreated,
    buyerEmail,
    new { orderId = domainEvent.Order.Id });

We have an email in the system now. The bigger result is the communications boundary around it.

The one piece of that call that won't last is buyerEmail.

Next up, we'll stop Ordering from passing an email address, and have Communications resolve the buyer through Identity and enrich the order with product details from Catalog.

Part 1: Where Should Communications Live?

Jeremy — Sun, 18 Oct 2026 23:00:00 +0000

Almost every application sends communications. Most of us call them notifications: order confirmations, password resets, welcome emails, shipping updates, security alerts. They're so ordinary that, while an application is new, nobody treats them as a separate architectural concern.

They usually start like this:

await emailClient.SendAsync(...);

Maybe the application uses an SMTP server. Maybe it starts with a provider such as SendGrid. Either way the requirement is simple. Something happened, and the business rules say somebody needs to hear about it.

For a small application this is often the right call. If the system sends a handful of emails and everything needed to build them is already in the same process, a separate communications architecture is a lot of infrastructure that won't pay for itself any time soon.

Microsoft's .NET eShop reference application isn't small, and that makes it a good place to study the problem. It's already split along business contexts. Ordering owns orders. Identity owns users and authentication. Payment processing runs as its own service and reports outcomes back through integration events. The services talk through deliberate contracts instead of sharing one convenient object graph.

eShop doesn't send customer communications today. If we added an order confirmation the way most applications start, we'd inject an IEmailClient into Ordering and call it a day, and that small change would start working against the boundaries eShop was built around.

This series adds a communications service to eShop. Before writing any code, we'll work out where the service's boundary belongs and why.

The full source for every part of the series is in the eShop sample in the Transmitly repository. Each part has its own folder, and each one builds on the code from the part before.

An order communication crosses domain boundaries

Take the confirmation we send after an order is created. Ordering looks like the obvious owner. It knows the order exists, and it holds the order number, line items, quantities, and the rest of the ordering data.

But a good order communication might also include the recipient's name and email address, payment information, shipping details, localization settings, or communication preferences. Each of those has a natural owner, and that owner isn't necessarily Ordering.

You can see this in eShop. Ordering has its own model of a buyer, shaped for ordering. It keeps an identity identifier and whatever else Ordering needs to do its work. That model doesn't need to grow into a full representation of the user's identity just because we eventually want to send a message.

Payment works the same way. It has its own lifecycle and sends relevant outcomes across a boundary. Ordering reacts to those outcomes and keeps ownership of its own state.

This is one of the practical payoffs of Domain-Driven Design: a bounded context models only what it needs for its own responsibilities.

Ordering understands a buyer in terms of placing and managing orders. Identity understands the same person differently, and Payment sees the transaction through yet another model. Those representations can coexist without collapsing into one universal Customer object that every component in the system shares.

Communications complicate this, because a message often needs a view of the business that spans several of those boundaries.

An order confirmation is a representation, built for a recipient, of something that happened in the business. Serializing the Order into HTML only covers part of it. Building the message may take data from Ordering, Identity, Payment, Shipping, and other contexts.

That makes the ownership question easier to answer. The order may be the reason a communication exists, but the communication has its own model and its own lifecycle.

When composition leaks back into the originating domain

Say we make Ordering responsible for the whole communication. At first it needs only an order and an email address. Over time the message gets more useful, and more useful means more information.

Customer service wants the payment status included. Product wants an estimated delivery date. Marketing wants localized copy. Later, customers get to choose between email, SMS, and push notifications.

The flow starts to look like this:

Order Created
     |
     v
 Ordering
     |
     +------> Identity
     |         recipient information and preferences
     |
     +------> Payment
     |         payment state
     |
     +------> Shipping
     |         delivery information
     |
     v
 Compose Communication
     |
     v
 Render Content
     |
     v
 Select Channel / Provider
     |
     v
 Deliver

There's rarely a single moment when this feels obviously wrong. Every new dependency shows up attached to a reasonable requirement. We need the recipient's email address, so we fetch it. We need the payment status, so we fetch that too. Eventually Ordering has become an orchestrator for data and behavior that exist mostly to produce customer communications.

The dependency is easy to miss because the communication really is about an order. The question is what each domain is responsible for knowing.

Ordering should know that an order was created, paid, cancelled, or shipped, along with the identifiers and facts it needs to perform ordering behavior. It doesn't follow that Ordering should also know how those facts are presented to a recipient, where the recipient's addresses come from, which channels are appropriate, or how delivery works. Those concerns make up a domain of their own.

What eShop's existing boundaries already show

eShop already has the kind of separation we want to keep. Information moves between parts of the application through deliberate contracts, so no domain has to understand another domain's internals.

Integration events are one way eShop does this. A payment result can cross a service boundary as a fact, letting Ordering update the state it owns. An order status change can be published the same way, for any consumer with its own reason to care.

That's a good pattern for boundaries. It's tempting to stretch it further and make Communications one more subscriber that watches those events for something worth sending, but a communication intent means something different from an integration event.

An integration event says something happened and makes that fact available to whoever is interested. A communication intent says the service that owns a business operation has decided there is now something to communicate. The two can come from the same operation and still serve different purposes.

Take an order that has just been created:

                    Ordering
                       |
                 Order is created
                       |
            +----------+----------+
            |                     |
            v                     v
    Integration Event      Communication Intent
            |                     |
            v                     v
      Other Services        Communications

Ordering owns the business operation, so it's the natural place to decide that the operation creates a communication intent.

It doesn't have to wait for a communications service to notice an event and guess that a message would probably help. The business behavior can be explicit: this operation produces an OrderCreated communication intent. From there, the intent belongs to the communications domain, which gives us the boundary:

The service that owns the business operation creates the communication intent. The communications domain owns the lifecycle of that intent.

Communication intent describes purpose

The word intent separates the reason for communicating from the mechanism that fulfills it.

Suppose Ordering dispatches an intent named:

OrderCreated

From Ordering's side, that intent can stay small: an order identifier, the buyer's identity identifier, a payment identifier, and anything else Ordering legitimately owns and considers relevant to the communication.

Conceptually:

Ordering
    |
    | OrderCreated
    | orderId: 123
    | paymentId: xyz
    | recipientId: abc
    | itemCount: 4
    v
Communications

Ordering has said why the communication exists, and Communications now has enough to start fulfilling it.

Today's communication policy might produce a single email:

OrderCreated
     |
     v
   Email

As the product evolves, the same intent might produce both email and SMS:

OrderCreated
     |
     +----> Email
     |
     +----> SMS

Later, channel selection might depend on recipient preferences, geography, account type, urgency, or other communication-specific rules.

None of those changes alter the intent, which is still to tell someone that an order was created. They change the organization's communication policy around it.

So Ordering has no reason to bake today's delivery strategy into an abstraction like SendOrderConfirmationEmail. That name welds together two decisions that change for different reasons: why we are communicating, and which channel we happen to use right now.

OrderCreated is the more durable vocabulary. It states the business purpose and leaves the communications domain to decide what that purpose means operationally.

Communications becomes a domain of composition

Once an intent crosses into Communications, the problem shifts from managing business state to composing a communication.

An OrderCreated communication might need a model like this:

Order
    Ordering

Recipient
    Identity

Payment Status
    Payment

Delivery Information
    Shipping

Locale / Preferences
    Profile

The communications domain can build that model however suits the architecture. Some information gets resolved when the communication is composed. Some may already sit in a communications-oriented projection. Integration events can supply facts that Communications keeps for later. In more complex systems, an intent might be enriched gradually as related information arrives.

Which approach fits depends on latency, consistency, resilience, and how much data is involved. Those are implementation details inside the larger ownership model.

Ordering supplies the identifiers and facts it owns. Communications assembles the communication model, so the cross-domain work happens in one place.

It also gives Communications a coherent set of responsibilities. Recipient resolution, message composition, localization, channel policy, template rendering, provider selection, delivery reporting, scheduling, suppression, retries, and auditing all belong to the lifecycle of a communication. None of them belong to the lifecycle of an order.

Where Communications physically runs can vary. In one application it's a module; in another it's an independently deployed service. The architectural benefit comes from treating it as a separate responsibility before deciding where the code lives.

Intent has a lifecycle

One consequence of this model: a communication intent doesn't have to mean immediate delivery.

When communication code sits right beside the business operation, we drift toward a one-to-one relationship:

Business Event -> Message

An order is created, so an email goes out. A payment succeeds, so another email goes out. Another order, another message.

That works until communication policy gets more sophisticated.

Say a customer places five separate orders in a short window, and each payment is processed independently. A straightforward implementation could send five order confirmations followed by five payment confirmations. Every event was communicated correctly, and the customer still got ten emails.

Maybe the real requirement is to wait for those payments to settle, then send the customer one summary with the orders and their payment statuses.

With a communications domain, the intent can outlive the operation that created it:

OrderCreated #1 ----\
OrderCreated #2 -----\
OrderCreated #3 ------\
OrderCreated #4 -------> Communications
OrderCreated #5 ------/       |
                              | accumulate
                              | correlate
Payment facts --------->      | enrich
                              |
                              v
                     Communication ready
                              |
                              v
                       One summary

Ordering doesn't need to know the recipient just placed four other orders, and Payment doesn't need to understand the customer's notification experience. Each domain keeps owning its own business behavior.

Communications owns the correlation of intents and the policy that decides when a communication is ready to be composed and delivered.

This is where communication intent differs from a generic event stream. Communications isn't consuming every event in the system and trying to work out which ones deserve a message. The originating services have already stated the intent. Other events and projections may supply information used to fulfill it, but the intent itself is explicit, which lets communication policy operate over time without turning the business domains into communication orchestrators.

Some communications are imperative

Not every communication leaves the decisions to Communications.

With an intent like OrderCreated, the communications domain decides almost everything: who receives it, which channels to use, whether to send now or wait, even whether to send anything at all. The originating domain only says that something worth communicating happened.

Imperative communications flip that. The originating domain has already decided what must happen, often down to the recipient, the channel, and sometimes the provider.

Take an escheatment notice. Before a business turns unclaimed property over to the state, it may be required to notify the owner by certified mail at their last known address. The recipient is fixed. The channel is fixed. Email isn't an acceptable substitute, and neither is the customer's stated preference for SMS. The provider may be fixed too, if only one vendor can produce the proof of certified delivery the business needs to keep.

A one-time passcode is a smaller example. Identity needs the code delivered by SMS to the phone number registered on the account, even if the customer would rather get email, and not by push either. Letting channel policy choose here would undermine the security the code exists to provide.

In both cases, decisions that Communications would normally own are made upstream, because they're part of the business rule itself.

That doesn't move the rest of the work back into the business domain. Identity shouldn't be retrying SMS sends or tracking delivery receipts, and whoever owns escheatment shouldn't be integrating directly with a certified mail vendor. Communications still owns fulfillment: rendering the approved template, attempting delivery, retrying, escalating when delivery fails, and keeping the audit history and evidence of delivery that a regulator or security review may ask for.

So the boundary moves, but it doesn't go away. An intent hands Communications a purpose and lets it decide how to fulfill it. An imperative hands it a purpose along with constraints it has to honor. Either way, the business domain decides what must happen, and Communications is accountable for making it happen.

Templates belong with the communication model

With composition living in Communications, templates get easier to reason about too.

An OrderCreated communication may eventually have an email subject, an HTML body, a plain-text body, an SMS variation, a push-notification title, and localized versions of each.

The organization might keep those templates in source control, give Product or Marketing tooling to maintain them, or use a content-management system. That choice can change without touching who owns the underlying order.

Changing:

Thanks for your order!

to:

Thanks, Alice! We've received order #123.

is a communication change. So is adding an SMS version, and so is localizing the message. Moving from SMTP to SendGrid is a delivery change. None of them touch the Ordering model.

Keeping composition inside Communications means content can change as customer-experience requirements change, while the business domains that started the communication stay focused on their own models.

The transport is only one part of the problem

When communications first get complicated, provider abstraction tends to get most of the attention. Swapping SMTP for SendGrid, or one SMS provider for another, is an obvious dependency to isolate.

Provider independence is useful, but it sits near the bottom of the communications problem.

As the system matures, the harder questions are about policy and composition. Why does this communication exist? Who should receive it, and what information does composing it require? Should it go out now, or wait and be combined with other intents? Which channels and preferences apply? What happens when delivery fails?

Those questions belong together because they all describe the lifecycle of communicating with a recipient.

The resulting split looks like this:

Business Domains
      |
      | communication intents
      | communication imperatives
      v
Communications
      |
      | resolve
      | enrich
      | accumulate
      | compose
      | apply policy
      | deliver
      v
Email / SMS / Push / ...

The business domains stay responsible for the facts and rules they own. Communications is responsible for turning explicit communication requirements into messages that are composed and delivered correctly.

Applying the model to eShop

When Ordering completes an operation like creating an order, it stays the authority on that business action. As part of completing it, Ordering can express an OrderCreated communication intent using the identifiers and facts it owns.

The rest of the lifecycle moves to Communications:

                 Ordering
                    |
              Order created
                    |
                    v
             OrderCreated
                 intent
                    |
                    v
              Communications
                    |
             resolve recipient
                    |
             gather/enrich data
                    |
              compose content
                    |
              apply policy
                    |
             +------+------+
             |      |      |
           Email   SMS    Push

Integration events still matter here. They carry facts between bounded contexts and can give Communications what it needs to enrich or complete an existing intent. They just don't need to be the way Communications discovers that a communication should exist, because the business service can state that decision directly.

Business intent stays explicit where the business operation happens, and communication policy stays in one place, the domain responsible for communication.

Where Transmitly enters the picture

Nothing so far depends on Transmitly. It's an architecture problem.

The goal is a boundary that pays off once communications start spanning domains, channels, providers, and time. Choosing a library comes after that.

Ordering expresses something like OrderCreated using information it legitimately owns. Communications accepts that intent and owns its lifecycle from there. Recipient resolution, composition, templates, channel selection, providers, and delivery all stay on the communications side of the boundary.

Transmitly is one way to implement that model. In the next article we'll add it to the .NET eShop codebase and put that boundary around an order communication. We'll start with simulated delivery so SMTP credentials and provider configuration don't distract from the architecture.

Ordering
    |
    | OrderCreated
    v
Communications

Ordering stays responsible for knowing that an order was created and that the operation gives it a reason to communicate. After that, the communication belongs to a domain built to compose and deliver it.

Next, we'll start writing code. Ordering will dispatch its OrderCreated intent, and a new Communications service will turn it into an email.

Sending Transactional Emails with Transmitly (C#)

Jeremy — Tue, 29 Oct 2024 18:00:00 +0000

Whether you’re confirming an order, resetting a password, or sending an account notification, transactional emails are key to ensuring a smooth user experience. However, managing these emails effectively can be complex. That’s where Transmitly comes in — a solution designed to streamline and enhance your transactional email process. In this article, you’ll explore how Transmitly, with its powerful features, can revolutionize the way you handle email communication.

What are Transactional Emails?

Transactional emails are messages sent in response to specific actions or events within your application or service. Unlike marketing emails, which are sent in bulk to promote products or services, transactional emails are integral to your business operations. Common examples include:

Order confirmations
Password reset requests
Account notifications
Shipping updates
Appointment reminders

What is Transmitly?

Transmitly is a robust platform for managing and controlling outgoing transactional communications, including emails, SMS, and push notifications. It centralizes your communication management, offers flexible configuration, and simplifies message composition. Whether you’re a developer or running a business, Transmitly helps you streamline your communication processes. It supports multiple service providers and integrates easily with a variety of tools, making your communications more efficient and reliable.

Methods of Sending Email

SMTP: Gmail, Zoho, Custom Mail Servers, SendGrid
3rd-Party Service Providers: SendGrid, Infobip, Mailgun, and more

Without Transmitly

Typically, your first few email communications might involve using Simple Mail Transfer Protocol (SMTP) servers because it’s the simplest and fastest method to implement.

A common approach:

using System.Net;
using System.Net.Mail;
public class EmailService : IEmailService
{
  public void SendPasswordReminder(string toEmail, string subject, string body)
  {
      var fromAddress = new MailAddress("your-from-email@example.com", "Your Name");
      var toAddress = new MailAddress(toEmail);
      const string fromPassword = "your-email-password";

      var smtp = new SmtpClient
      {
          Host = "smtp.example.com",
          Port = 587,
          EnableSsl = true,
          DeliveryMethod = SmtpDeliveryMethod.Network,
          UseDefaultCredentials = false,
          Credentials = new NetworkCredential(fromAddress.Address, fromPassword)
      };

      using (var message = new MailMessage(fromAddress, toAddress)
      {
          Subject = subject,
          Body = body
      })
      {
          smtp.Send(message);
      }
  }
}

What’s Wrong with This Approach?

While this method works for low-volume emails, it has several limitations if you need to scale:

Scalability Issues: Handling a high volume of emails can strain your SMTP server, especially if it’s not optimized for large-scale sending.
Deliverability Concerns: Ensuring your emails land in the recipient’s inbox (and not their spam folder) requires constant monitoring and fine-tuning, often without much insight or tooling.
Limited Features: Basic SMTP solutions lack advanced features like email templates, scheduling, and automated workflows.
Security Risks: Directly managing email sending involves handling sensitive credentials and configurations, which increases the risk of security breaches.

The Transmitly Way

First, you need to install the nuget package:

# Install the base Transmitly package
dotnet add package Transmitly

# We'll need the SMTP Transmitly package
dotnet add package Transmitly.ChannelProvider.Smtp

# To make our lives easier, we'll use the optional MS DI extensions 
dotnet add package Transmitly.Microsoft.Extensions.DependencyInjection

We need to do a little configuration first. In your Startup.cs

//All usual extensions and properties are located in this root namespace
using Transmitly;
//SecureSocketOptions comes from the Smtp configuration namespace
using Transmitly.ChannelProvider.Smtp.Configuration;
...
//AddTransmitly comes from MS DI extensions library.
//Without the MS DI library, you can still wire up Transmitly using its
//fluent builder.
services.AddTransmitly(tly=>{ 
  tly
  //AddSmtpSupport comes from the Smtp library
  //This allows us to setup what's needed in a strongly typed and central way
  .AddSmtpSupport(options =>
  {
    options.Host = "smtp.example.com";
    options.Port = 587;
    options.SocketOptions = SecureSocketOptions.StartTls;
    options.UserName = "MySMTPUsername";
    options.Password = "MyPassword";
  })
  //A Pipeline defines a communication, in this case a single email.
  //Something you can learn more about in the GitHub docs
  .AddPipeline("SendPasswordReminder", pipeline =>
  {
    pipeline.AddEmail("your-from-email@example.com".AsIdentityAddress("Your Name"), email =>
    {
      email.Subject.AddStringTemplate("Reset your password");
      email.HtmlBody.AddStringTemplate("<a href=\"https://url.com/reset-password\">Click here to reset your password</a>");
    });
  });
});

At first glance, it looks similar to the original SMTP code. You still have credentials and email content, but now everything is centralized. Configuration is placed in your Startup.cs, but as your system grows, you can easily move this into its own class library.

With Transmitly, you’re also creating a communications pipeline, which gives you centralized control over your communications. You can manage what messages are available and which channel providers are used to send them. In short, you now have a loosely coupled, centralized way of managing your communications.

Next, let’s modify our original sending code:

using Transmitly;

public class EmailService : IEmailService
{
  private readonly ICommunicationsClient _commsClient;

  public EmailService(ICommunicationsClient commsClient)
  {
    _commsClient = commsClient;
  }

  public async Task SendPasswordReminder(string toEmail)
  {
      var result = await _commsClient.DispatchAsync("SendPasswordReminder", toEmail, new { });

      if (result.IsSuccessful)
      {
          Console.WriteLine("Email sent successfully!");
      }
      else
      {
          Console.WriteLine("Failed to send email.");
      }
  }
}

That’s all there is to it! The code may look similar, but these changes open up several new possibilities:

Change Channels: While today you might only need email, in the future, you might want to add push notifications or give users communication preferences. Transmitly lets you manage that easily with Pipelines, Channels, and Channel Providers.
Change Providers: If SMTP gives you issues, you can quickly switch to another provider, like SendGrid, Mailgun, or Infobip, by adding a new Transmitly library and updating your configuration.

You now have the power and flexibility to grow your communication strategy in a safe, controlled, and testable manner.

Key Benefits of Using Transmitly

Centralized Communication Management: Manage emails, SMS, and push notifications from one platform, reducing complexity and boosting efficiency.
Flexible Configuration: Switch between service providers like SendGrid, Twilio, or SMTP without altering your code.
Simplified Message Composition: Externalize message composition, making it easier to modify and manage your communication strategy.
Scalability and Reliability: Designed for high-volume communications with reliable performance.
Provider Agnostic: Integrates seamlessly with almost any communication service (e.g., Twilio, Infobip, SMTP).

Conclusion

Transactional emails are vital to modern applications, ensuring timely and effective communication with users. While traditional email-sending methods can be limiting, Transmitly offers a powerful alternative that simplifies the process, improves deliverability, and provides valuable insights. By integrating Transmitly into your app, you can ensure your transactional emails are sent efficiently and reliably, enhancing user experience and engagement.

For more information check out the Transmitly GitHub Repo.

Sending SMS with Transmitly (C#)

Jeremy — Wed, 23 Oct 2024 06:00:00 +0000

Whether you’re confirming an order, resetting a password, or sending an account notification, SMS messages are key to ensuring a great user experience. However, managing these SMS messages effectively can get complex, fast. That’s where Transmitly comes in — a solution designed to streamline and enhance your SMS message process. In this article, you’ll explore how Transmitly, with its powerful features, can revolutionize the way you handle SMS communications.

What is a transactional communication?

Transactional communications are sent in response to specific actions or events within your application or service. Unlike marketing communications, which are typically sent in bulk to promote products or services, transactional communications are integral parts of your business operations. Common examples include:

Order confirmations
Password reset requests
Account notifications
One time password (OTP)
Appointment reminders

What is Transmitly?

Methods of Sending SMS

SMS Gateway: Strangely enough, some carriers support sending SMS messages via special email addresses. They are generally not very reliable and you must know which provider your recipient is using.
3rd-Party Service Providers: Twilio, InfoBip, Plivo, and more

Without Transmitly

There’s quite a few options out there to choose from for SMS communications. There’s also a lot more restrictions to be allowed to send SMS with any service. We’ll assume you’ve made it through the hoops of getting setup and you’ve chosen Twilio.

Add the Twilio Api:

dotnet add package Twilio

// Install the C# / .NET helper library from twilio.com/docs/csharp/install
using System;
using Twilio;
using Twilio.Rest.Api.V2010.Account;
using System.Threading.Tasks;

class SmsService {

    public static async Task OrderProcessed(string recipient) {

        // Find your Account SID and Auth Token at twilio.com/console
        // and set the environment variables. See http://twil.io/secure
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
        string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");

        TwilioClient.Init(accountSid, authToken);

        var message = await MessageResource.CreateAsync(
            body: "Your order is being processed, thanks!",
            from: new Twilio.Types.PhoneNumber("+15017122661"),
            to: new Twilio.Types.PhoneNumber(recipient));
        Console.WriteLine(message.Body);
    }
}

(Example taken from the Twilio quick start)

What’s Wrong with This Approach?

On the surface, not a lot. Twilio and their SDK will work great for a long time.

More work to be done: Not shown is just how to deserialize the API response and make sense of it in your application.
Vendor Lock: The more communications, the more you’re going to use their API. That doesn’t pose a problem until something changes with their service. Price increases, API changes, etc are all going to cost you and your application.

The Transmitly Way

First, you need to install the nuget package:

# Install the base Transmitly package
dotnet add package Transmitly
# We'll need the Twilio Transmitly package to send SMS
dotnet add package Transmitly.ChannelProvider.Twilio
# To make our lives easier, we'll use the optional MS DI extensions 
dotnet add package Transmitly.Microsoft.Extensions.DependencyInjection

We need to do a little configuration first. In your Startup.cs

//All usual extensions and properties are located in this root namespace
using Transmitly;
...
//AddTransmitly comes from MS DI extensions library.
//Without the MS DI library, you can still wire up Transmitly using its
//fluent builder.
services.AddTransmitly(tly=>{ 
  tly
  //AddTwilioSupport comes from the Twilio library
  //This allows us to setup what's needed in a strongly typed and central way
  .AddTwilioSupport(twilio =>
  {
      twilio.AuthToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");
      twilio.AccountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
  })
  .AddPipeline("OrderProcessing", pipeline=>
  {
    //AddSms is a core feature, a channel, of Transmitly
    //Out of the box there are Email, SMS, Voice and Push
    //The first argument is the number we're sending from
    pipeline.AddSms("+15017122661".AsIdentityAddress(), sms=>{
      //Transmitly is a bit different. All of our communication content is configured by using templates.
      //Out of the box, we have string templates, embedded resource templates and custom template resolvers.
      //There are multiple types of templates to get you started. You can even create templates 
      //specific to certain cultures!
      sms.Message.AddStringTemplate("Your order is being processed, thanks!");
      //We've kept it simple for this example, but Transmitly also supports various template engines.
      //Adding a template engine can make your messages a bit more useful by showing the order# or user's name.
    });
  });
});

At first glance, it looks similar to the original code. You still have credentials and SMS content, but now everything is centralized. Configuration is placed in your Startup.cs, but as your system grows, you can easily move this into its own class library.

Next, let’s modify our original sending code:

using Transmitly;

public class SmsService
{
  private readonly ICommunicationsClient _commsClient;

  public SmsService(ICommunicationsClient commsClient)
  {
    _commsClient = commsClient;
  }

  public async Task OrderProcessed(string recipient)
  {
    //Dispatch (send) the transactional sms to our recipient using our configured Twilio account and our "OrderProcessing" pipeline.
    var result = await _commsClient.DispatchAsync("OrderProcessing", recipient, new { });

    if (result.IsSuccessful)
    {
        Console.WriteLine("Sms sent successfully!");
    }
    else
    {
        Console.WriteLine("Failed to send SMS");
    }
  }
}

That’s all there is to it! The code may look similar, but these changes open up several new possibilities:

Change Channels: While today you might only need SMS, in the future, you might want to add email, push notifications or better yet, let users set their communication preferences. Transmitly lets you manage that easily with Pipelines, Channels, and Channel Providers.
Change Providers: If Twilio gives you issues, you can quickly switch to another provider, like Infobip by adding a new Transmitly library and updating your configuration.

You now have the power and flexibility to grow your communication strategy in a safe, controlled, and testable manner.

Key Benefits of Using Transmitly

Centralized Communication Management: Manage emails, SMS, and push notifications from one platform, reducing complexity and boosting efficiency.
Flexible Configuration: Switch between service providers like SendGrid or Infobip without altering your business logic.
Simplified Message Composition: Externalize message composition, making it easier to modify and manage your communication strategy.
Scalability and Reliability: Designed for high-volume communications with reliable performance.
Provider Agnostic: Integrates seamlessly with almost any communication service (e.g., Twilio, Infobip, SMTP). Easily extensible for adding any missing features you might need.

Conclusion

Transactional communications are vital to modern applications, ensuring timely and effective communication with users. Transmitly offers a powerful alternative that simplifies the process, improves deliverability, and provides valuable insights. By integrating Transmitly into your app, you can ensure your transactional communications are sent efficiently and reliably, enhancing user experience and engagement.

Piqued your interest? Check out the Transmitly GitHub Repo for more exciting ways to manage your business' communications strategies.

Transactional Emails: A long term view

Jeremy — Thu, 17 Oct 2024 01:59:40 +0000

Sending emails has become essential for almost all modern applications and games. The most common type of emails in your first app are transactional. Examples of transactional communications include order confirmations, password reset requests, account notifications, and appointment reminders. Luckily, Microsoft has made this task pretty simple out of the box. So much so that you may not put much thought into how you’re sending out your app’s communications. And that’s okay — we all have deadlines to meet.

Getting Started

Once you’ve identified the required transactional communications for your app, you need to decide how to send them. Again, you’re in luck here, too. You have a few different options when deciding how to send your emails. To keep things simple, you can start by using an established SMTP server. There are countless examples of how to use Gmail, Zoho, and other third-party SMTP services. It’s simple enough and will get you through development and even to the MVP phase.

As your app grows, you might notice you’re being rate-limited by the SMTP service, transient errors are creeping in, and your simple email solution is no longer holding up to the stress of your growing app. First of all, congrats! Your app is growing! Second, it’s time to revisit our communications strategy. You’re in luck here as well. Numerous third-party APIs make it even easier to send emails. Services such as SendGrid, Mailgun, and ZeptoMail all come with their own pros and cons and a wide range of features. Now, you can do some really neat things with your emails. Again, your communications strategy has evolved, and so has the complexity.

Smooth Sailing…

You’ve chosen a third-party service you love, and it’s working great. You’ve created an email service using their SDK. Now you can get back to growing your app, team, and business. Unfortunately, you receive an email from your third-party service. They are increasing their prices… again. Or worse, they’ve moved a feature you’ve been using heavily behind an expensive paywall.

It’s time to change your service… again. It’s generally not too big of a deal, right? …Right?! Integrating a new email service only took a day. But the app is growing quickly, we have tech debt throughout, and not all of our emails are consistent. It wasn’t a big deal, but the new service doesn’t handle our older, legacy formats.

While it may only be a mild annoyance that only rears its ugly head every few years, you’ve got a successful app. You don’t have time to learn a new service, a new API, all the quirks of a new service, and regression test all of your communications… again. This is why the open-source Transmitly communications library was created.

Transmit-Who?

The Transmitly library is an open-source library designed to manage and control outgoing transactional communications, including emails, SMS, and push notifications. It offers centralized communication management, allowing developers to handle multiple communication channels from a single platform.

Transmitly provides flexible configuration, enabling easy switching between SMTP and service providers like SendGrid, Twilio, and Infobip without altering domain code. It simplifies message composition and delivery and integrates seamlessly with various dependency injection containers and template engines.

And Now for Something Completely Different

Transmitly is built on concepts pioneered by Serilog, Microsoft, and many other extensibility-first libraries. At its core, Transmitly enables you to choose as much or as little integration as you have the time or effort to use.

Love the idea? Convert your whole codebase in a day or two. Not sure? Try it on only new transactional communications to start. It’s up to you.

All this extensibility doesn’t come without some downsides. There’s going to be a ‘different’ way of doing things. And with different, there come some new terms we need to understand before we can really grasp the full scope of what’s possible.

Channels

A channel is the base of all communications. Out of the box, Transmitly supports email, SMS, voice and push notifications. But you’re not limited to these channels. Transmitly is built with extensibility in mind at all times. This means that if you have an idea for a channel; such as physical mail, fax, or Slack, practically any kind of channel can be built in.

Channel Providers

Channel Providers do the heavy lifting for your Channels. A Channel Provider can support one to many channels. Examples include SMTP (Email), SendGrid (Email), Infobip (Email & SMS), or Firebase (iOS/Android/App push notifications).

Pipelines

Pipelines are where the real power of Transmitly starts to materialize. With a pipeline, you gain control of managing communications in a single location. You can also manage which communications are available and which channel providers are allowed to send them.

That’s it! For now, at least. There are a few more advanced concepts that make the Transmitly transition even sweeter. For now, we’re sticking to the basics to get you up to speed ASAP. After all, you have a fast-growing application to maintain!

Writing Code

First, you’ll need to install the Transmitly NuGet library in your app:

# Install the base Transmitly package
dotnet add package Transmitly

# To make our lives easier, we'll use the optional MS DI extensions 
dotnet add package Transmitly.Microsoft.Extensions.DependencyInjection

Next, we’ll continue with our email theme by recreating a welcome email that is sent to a newly signed-up user of your app.

Program.cs

using Transmitly;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTransmitly(tly =>
{
    // Pipelines allow you to define your communications
    // as a domain action. This allows your domain code to 
    // stay agnostic to the details of how you
    // may send out a transactional communication.

    // Notice "WelcomeKit" doesn't specify the how or what
    // might be sent. This is our 'intent'. It's up to our configuration
    // or domain if any communications will spawn and to whom.
    tly.AddPipeline("WelcomeKit", pipeline =>
    {
        // AsIdentityAddress() is also a convenience method that helps us create an audience identity
        // Identity addresses can be anything: email, phone, or even a device/app ID for push notifications!
        pipeline.AddEmail("welcome@my.app".AsIdentityAddress("Welcome Committee"), email =>
        {
            // Transmitly is a bit different. Most channel content is configured by using 
            // templates. The immediate benefit out of the box is being able to configure
            // culture-based templates. 
            // For this example, we'll keep things simple and send a static message.
            // But as you may have guessed, Transmitly also has Template Engine plugins as well.
            email.Subject.AddStringTemplate("Thanks for creating an account!");
            email.HtmlBody.AddStringTemplate("Check out the <a href=\"https://my.app/getting-started\">Getting Started</a> section to see all the cool things you can do!");
            email.TextBody.AddStringTemplate("Check out the Getting Started (https://my.app/getting-started) section to see all the cool things you can do!");
        });
    });
});

Next, we can trigger this welcome kit to happen in the same place we used to send our email. Note how simple your domain logic becomes when we remove communications details.

Using Transmitly:

public class RegistrationService
{
    private readonly ICommunicationsClient _commsClient;

    public RegistrationService(ICommunicationsClient commsClient)
    {
        _commsClient = commsClient ?? throw new ArgumentNullException(nameof(commsClient));
    }

    public async Task<User> RegisterUser(string email, AccountDetail detail)
    {
        // Create user
        var newUser = new User(email);
        // Trigger the welcome kit email
        var result = await _commsClient.DispatchAsync("WelcomeKit", email, new { });
        if (result.IsSuccessful)
            return newUser;
        throw new RegistrationException("Registration failed. Rollback!");
    }
}

If you run this new code… technically, it will work. However, you’ll be disappointed that you’re no longer sending emails. This is because we have not yet defined the 'how' of sending the emails out. With Transmitly, the 'how' or services are referred to as Channel Providers. Channel Providers are what the name implies: they are providers for any given channel. Examples of channel providers are SMTP, Twilio, SendGrid, Infobip etc.

# We want to continue using SMTP for now, so we'll add the SMTP extension
dotnet add package Transmitly.ChannelProvider.Smtp

Now we can configure the SMTP server settings Transmitly will use for our pipeline intent, 'WelcomeKit'.

using Transmitly;

var builder = WebApplication.CreateBuilder(args);
// EmailSettingsConfiguration is your own settings class, bound from the "EmailSettings" section of appsettings.json
var emailConfig = builder.Configuration.GetRequiredSection("EmailSettings").Get<EmailSettingsConfiguration>();

builder.Services.AddTransmitly(tly =>
{
    // Configure the SMTP Channel Provider Settings
    tly.AddSmtpSupport(smtp =>
    {
        smtp.Host = emailConfig.Host;
        smtp.Port = emailConfig.Port;
        smtp.UserName = emailConfig.Username;
        smtp.Password = emailConfig.Password;
    })
    // Pipelines allow you to define your communications
    // as a domain action. This allows your domain code to 
    // stay agnostic to the details of how you
    // may send out a transactional communication.
    .AddPipeline("WelcomeKit", pipeline =>
    {
        // AsIdentityAddress() is also a convenience method that helps us create an audience identity
        // Identity addresses can be anything: email, phone, or even a device/app ID for push notifications!
        pipeline.AddEmail("welcome@my.app".AsIdentityAddress("Welcome Committee"), email =>
        {
            // Transmitly is a bit different. Most channel content is configured by using 
            // templates. The immediate benefit out of the box is being able to configure
            // culture-based templates. 
            // For this example, we'll keep things simple and send a static message.
            // But as you may have guessed, Transmitly also has Template Engine plugins as well.
            email.Subject.AddStringTemplate("Thanks for creating an account!");
            email.HtmlBody.AddStringTemplate("Check out the <a href=\"https://my.app/getting-started\">Getting Started</a> section to see all the cool things you can do!");
            email.TextBody.AddStringTemplate("Check out the Getting Started (https://my.app/getting-started) section to see all the cool things you can do!");
        });
    });
});

After deploying your code, sending a simple email can remain just as easy as it was before.

If SMTP doesn’t quite fit the bill for your app anymore, try a different channel provider.

Adding SMS or push notifications? Communication preferences? Modify your pipelines to effortlessly add new channels. Handling your user communication preferences are just as easy.

Conclusion

As your app grows and evolves, having a flexible and scalable communication strategy is crucial. Transmitly not only simplifies the process of sending transactional communications but also provides a robust framework for handling various channels and channel providers. This reduces the time spent managing communication logic and enables you to focus on building and improving your core application.

Check out the Transmitly GitHub repo if you're interested in learning more!

Happy holidays from the C# Advent Calendar 2024!

Transactional Emails: From SMTP to Transmitly

Jeremy — Mon, 02 Sep 2024 21:21:06 +0000

Getting Started

Smooth Sailing…

Transmit-Who?

Transmitly provides flexible configuration, enabling easy switching between SMTP (MailKit) and service providers like SendGrid, Twilio, and Infobip without altering domain code. It simplifies message composition and delivery and integrates seamlessly with various dependency injection containers and template engines.

And Now for Something Completely Different

Love the idea? Convert your whole codebase in a day or two. Not sure? Try it on only new transactional communications to start. It’s up to you.

Channels

A channel is the base of all communications. Out of the box, Transmitly supports email, SMS, and push notifications. But you’re not limited to these channels. Transmitly is built with extensibility in mind at all times. This means that if you have a need for any kind of channel, such as physical mail, fax, or Slack, practically any kind of channel can be built in.

Channel Providers

Channel Providers do the heavy lifting for your Channels. A Channel Provider can support one to many channels. Examples include MailKit (SMTP Email), SendGrid (Email), Infobip (Email & SMS), or Firebase (iOS/Android/App push notifications).

Pipelines

Writing Code

First, you’ll need to install the Transmitly NuGet library in your app:

# Install the base Transmitly package
dotnet install Transmitly

# To make our lives easier, we'll use the optional MS DI extensions 
dotnet install Transmitly.Microsoft.Extensions.DependencyInjectionbash

Next, we’ll continue with our email theme by recreating a welcome email that is sent to a newly signed-up user of your app.

Startup.cs

using Transmitly;

var builder = WebApplication.CreateBuilder(args);
var emailConfig = builder.Configuration.GetRequiredSection("EmailSettings").Get<EmailSettingsConfiguration>();

builder.Services.AddTransmitly(tly =>
{
    // Pipelines allow you to define your communications
    // as a domain action. This allows your domain code to 
    // stay agnostic to the details of how you
    // may send out a transactional communication.
    tly.AddPipeline("WelcomeKit", pipeline =>
    {
        // AsIdentityAddress() is also a convenience method that helps us create an audience identity
        // Identity addresses can be anything: email, phone, or even a device/app ID for push notifications!
        pipeline.AddEmail("welcome@my.app".AsIdentityAddress("Welcome Committee"), email =>
        {
            // Transmitly is a bit different. Most channel content is configured by using 
            // templates. The immediate benefit out of the box is being able to configure
            // culture-based templates. 
            // For this example, we'll keep things simple and send a static message.
            // But as you may have guessed, Transmitly also has Template Engine plugins as well.
            email.Subject.AddStringTemplate("Thanks for creating an account!");
            email.HtmlBody.AddStringTemplate("Check out the <a href=\"https://my.app/getting-started\">Getting Started</a> section to see all the cool things you can do!");
            email.TextBody.AddStringTemplate("Check out the Getting Started (https://my.app/getting-started) section to see all the cool things you can do!");
        });
    });

Next, we can trigger this welcome kit to happen in the same place we used to send our email. Note how simple your domain logic becomes when we remove communications details.

Using Transmitly:

public class RegistrationService
{
    private readonly ICommunicationsClient _commsClient;

    public RegistrationService(ICommunicationsClient commsClient)
    {
        _commsClient = commsClient ?? throw new ArgumentNullException(nameof(commsClient));
    }

    public async Task<User> RegisterUser(string email, AccountDetail detail)
    {
        // Create user
        var newUser = new User(email);
        // Trigger the welcome kit email
        var result = await _commsClient.DispatchAsync("WelcomeKit", email, TransactionalModel.Create(new { }));
        if (result.IsSuccessful)
            return newUser;
        throw new RegistrationException("Registration failed. Rollback!");
    }
}

If you run this new code… technically, it will work. However, you’ll be disappointed that you’re no longer sending emails. This is because we have not yet defined the ‘how’ of sending the emails out. With Transmitly, the “how” or services are referred to as Channel Providers. Channel Providers are what the name implies: they are providers for any given channel (email, SMS, push, etc.).

# We want to continue using SMTP for now, so we'll add the MailKit extension
dotnet install Transmitly.ChannelProvider.MailKit

Now we can configure the SMTP server settings Transmitly will use for our WelcomeKit.

using Transmitly;

var builder = WebApplication.CreateBuilder(args);
var emailConfig = builder.Configuration.GetRequiredSection("EmailSettings").Get<EmailSettingsConfiguration>();

builder.Services.AddTransmitly(tly =>
{
    // Configure the MailKit Channel Provider Settings
    tly.AddMailKitSupport(mailkit =>
    {
        mailkit.Host = emailConfig.Host;
        mailkit.UseSsl = emailConfig.UseSsl;
        mailkit.Port = emailConfig.Port;
        mailkit.UserName = emailConfig.Username;
        mailkit.Password = emailConfig.Password;
    })
    // Pipelines allow you to define your communications
    // as a domain action. This allows your domain code to 
    // stay agnostic to the details of how you
    // may send out a transactional communication.
    .AddPipeline("WelcomeKit", pipeline =>
    {
        // AsIdentityAddress() is also a convenience method that helps us create an audience identity
        // Identity addresses can be anything: email, phone, or even a device/app ID for push notifications!
        pipeline.AddEmail("welcome@my.app".AsIdentityAddress("Welcome Committee"), email =>
        {
            // Transmitly is a bit different. Most channel content is configured by using 
            // templates. The immediate benefit out of the box is being able to configure
            // culture-based templates. 
            // For this example, we'll keep things simple and send a static message.
            // But as you may have guessed, Transmitly also has Template Engine plugins as well.
            email.Subject.AddStringTemplate("Thanks for creating an account!");
            email.HtmlBody.AddStringTemplate("Check out the <a href=\"https://my.app/getting-started\">Getting Started</a> section to see all the cool things you can do!");
            email.TextBody.AddStringTemplate("Check out the Getting Started (https://my.app/getting-started) section to see all the cool things you can do!");
        });
    });

After deploying your code, sending a simple email can remain just as easy as it was before.

If SMTP doesn’t quite fit the bill for your app anymore, try a different channel provider.

Adding SMS or push notifications? Communication preferences? Modify your pipelines to effortlessly add new channels. Handling your user communication preferences are just as easy.

Conclusion

Check out the github repo for more details and examples of all the great things Transmitly can do.