IBeam.Communications.Email.AzureCommunications 2.6.0

IBeam.Communications.Email.AzureCommunications

IBeam.Communications.Email.AzureCommunications implements IBeam email delivery through Azure Communication Services Email. It lets application services depend on IEmailService while this provider handles Azure-specific connection setup, submission, validation, and provider exception translation.

When To Use This

• You use Azure Communication Services as your production email provider.
• You want domain services to stay independent of the Azure SDK.
• You want Azure request/provider failures translated into IBeam communication exceptions.
• You want one email provider registration that can be swapped without changing service code.

What This Package Contains

Architecture Fit

API <-- DTO/model object --> Service <-- Entity --> Repository

This package is a provider implementation. It should sit behind services that call IEmailService. It should not contain business rules, API response logic, tenant authorization, or persistence logic.

Quick Start

using IBeam.Communications.Abstractions;
using IBeam.Communications.Email.AzureCommunications;

builder.Services.AddIBeamCommunications(builder.Configuration);
builder.Services.AddIBeamAzureCommunicationsEmail(builder.Configuration);

Configuration:

{
  "IBeam": {
    "Communications": {
      "Email": {
        "FromAddress": "DoNotReply@contoso.com",
        "FromName": "Contoso"
      }
    }
  }
}

{
  "IBeam": {
    "Communications": {
      "Email": {
        "Providers": {
          "AzureCommunications": {
            "ConnectionString": "endpoint=https://example.communication.azure.com/;accesskey=..."
          }
        }
      }
    }
  }
}

Send an email:

public sealed class ReceiptService
{
    private readonly IEmailService _email;

    public ReceiptService(IEmailService email)
    {
        _email = email;
    }

    public Task SendReceiptAsync(string to, CancellationToken ct = default)
    {
        var message = new EmailMessage
        {
            Subject = "Your receipt",
            HtmlBody = "<p>Thanks for your purchase.</p>",
            TextBody = "Thanks for your purchase."
        };
        message.To.Add(to);

        return _email.SendAsync(message, ct: ct);
    }
}

Configuration

The provider connection string must look like:

endpoint=https://<resource>.communication.azure.com/;accesskey=<key>

Service Operations, Auditing, And Permissions

This provider does not own audit or permission decisions. The consuming service that decides to send the email should be tagged and wrapped.

[IBeamOperation("billing.receipt.send")]
public Task SendReceiptAsync(Guid tenantId, Guid receiptId, CancellationToken ct = default)
    => _operations.ExecuteAsync(
        this,
        token => SendReceiptCoreAsync(tenantId, receiptId, token),
        new ServiceOperationExecutionOptions
        {
            TenantId = tenantId,
            EntityId = receiptId
        },
        ct);

Keep Azure provider code focused on delivery mechanics. Put business decisions, permission rules, and audit boundaries in the service layer that calls IEmailService.

Data Storage

This package does not create tables or durable stores.

Extension Points

Package Relationships

Extended Examples And Agent Guidance

• Project agent prompt: .agent/prompt.md
• Repository implementation guide: ../.agent/implementation-guide.md
• Consuming API migration prompt: ../IBeam.AI.Enablement/examples/consuming-api-migration-prompt.md

Troubleshooting

Version Notes

• Targets net10.0.
• Uses Azure.Communication.Email.
• Package version is assigned by the repository release workflow.