IBeam.Communications.Email.SendGrid 2.9.1

IBeam.Communications.Email.SendGrid

IBeam.Communications.Email.SendGrid implements IEmailService using SendGrid. It lets application and domain services send email through IBeam abstractions without taking a direct dependency on SendGrid SDK types.

When To Use This

• You use SendGrid for production or staging email.
• You want provider reliability while keeping business services provider-neutral.
• You need SendGrid sandbox mode for staging environments.
• You want SendGrid failures translated into IBeam communication exceptions.

What This Package Contains

Architecture Fit

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

This package is a provider boundary. Domain services call IEmailService; this package performs SendGrid delivery. Controllers should not call SendGridClient, and repositories should not send email.

Quick Start

using IBeam.Communications.Abstractions;
using IBeam.Communications.Email.SendGrid;

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

Configuration:

{
  "IBeam": {
    "Communications": {
      "Email": {
        "FromAddress": "noreply@example.com",
        "FromName": "Example App",
        "SendGrid": {
          "ApiKey": "<sendgrid-api-key>",
          "DefaultFromAddress": "noreply@example.com",
          "DefaultFromDisplayName": "Example App",
          "SandboxMode": false
        }
      }
    }
  }
}

Send email:

public sealed class InvitationService
{
    private readonly IEmailService _email;

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

    public Task SendInviteAsync(string recipient, CancellationToken ct = default)
    {
        var message = new EmailMessage
        {
            Subject = "You are invited",
            HtmlBody = "<p>Open the app to accept your invite.</p>",
            TextBody = "Open the app to accept your invite."
        };
        message.To.Add(recipient);

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

Configuration

Service Operations, Auditing, And Permissions

The SendGrid provider is not the audit boundary. Tag and wrap the consuming service operation.

[IBeamOperation("accounts.invite")]
public Task InviteAsync(Guid tenantId, Guid inviteId, CancellationToken ct = default)
    => _operations.ExecuteAsync(
        this,
        token => InviteCoreAsync(tenantId, inviteId, token),
        new ServiceOperationExecutionOptions
        {
            TenantId = tenantId,
            EntityId = inviteId
        },
        ct);

Operation names such as accounts.invite can later be used by IBeam access-control rules and audit queries.

Data Storage

This package does not create database tables, Azure Table Storage tables, or local 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 SendGrid and SendGrid.Extensions.DependencyInjection.
• Package version is assigned by the repository release workflow.