IBeam.Communications.Email.PickupDirectory 2.9.0

IBeam.Communications.Email.PickupDirectory

IBeam.Communications.Email.PickupDirectory implements IEmailService by writing .eml email files to a local pickup directory. It is intended for local development, integration tests, QA inspection, and environments where you want to verify generated email without sending it to real recipients.

When To Use This

• You want to inspect email output without delivering it.
• You need a simple local/test email provider.
• You want automated tests to verify generated .eml files.
• You are developing templates and want fast feedback.

Do not treat this package as a production email delivery provider.

What This Package Contains

Architecture Fit

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

This provider belongs behind the service layer. It should not contain business decisions. Consuming services decide when email should be sent, and this provider writes the message to disk for inspection.

Quick Start

using IBeam.Communications.Abstractions;
using IBeam.Communications.Email.PickupDirectory;

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

Configuration:

{
  "IBeam": {
    "Communications": {
      "Email": {
        "FromAddress": "noreply@example.test",
        "FromName": "Local Test App",
        "PickupDirectory": {
          "DirectoryPath": "artifacts/email",
          "DefaultFromAddress": "noreply@example.test",
          "DefaultFromDisplayName": "Local Test App"
        }
      }
    }
  }
}

Send email:

public sealed class LocalEmailPreviewService
{
    private readonly IEmailService _email;

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

    public Task WritePreviewAsync(string to, CancellationToken ct = default)
    {
        var message = new EmailMessage
        {
            Subject = "Preview",
            HtmlBody = "<p>This message will be written as an .eml file.</p>"
        };
        message.To.Add(to);

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

Configuration

Service Operations, Auditing, And Permissions

Pickup-directory writes are still provider delivery, not the business operation. Tag the consuming service method that generates the email.

[IBeamOperation("notifications.preview.generate")]
public Task GeneratePreviewAsync(Guid tenantId, Guid notificationId, CancellationToken ct = default)
    => _operations.ExecuteAsync(
        this,
        token => GeneratePreviewCoreAsync(tenantId, notificationId, token),
        new ServiceOperationExecutionOptions
        {
            TenantId = tenantId,
            EntityId = notificationId
        },
        ct);

Data Storage

This package writes .eml files to the configured directory. It does not create database tables.

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.
• Intended for development/test/QA inspection, not production delivery.
• Package version is assigned by the repository release workflow.