Smtp2Go.NET 1.1.0

Smtp2Go.NET

Smtp2Go.NET is a strongly-typed .NET client library for the SMTP2GO transactional email API. It supports sending emails, webhook management, and email statistics with built-in HTTP resilience.

Installation

dotnet add package Smtp2Go.NET

Quick Start

Configuration (appsettings.json)

{
  "Smtp2Go": {
    "ApiKey": "api-YOUR-KEY-HERE",
    "BaseUrl": "https://api.smtp2go.com/v3/",
    "Timeout": "00:00:30"
  }
}

Registration (Program.cs)

// With HttpClient + resilience pipeline (recommended for production)
builder.Services.AddSmtp2GoWithHttp(builder.Configuration);

// Or with programmatic configuration
builder.Services.AddSmtp2GoWithHttp(options =>
{
    options.ApiKey = "api-YOUR-KEY-HERE";
});

Sending Email

public class EmailService(ISmtp2GoClient smtp2Go)
{
    public async Task SendWelcomeAsync(string recipientEmail)
    {
        var request = new EmailSendRequest
        {
            Sender = "noreply@yourdomain.com",
            To = [recipientEmail],
            Subject = "Welcome!",
            HtmlBody = "<h1>Welcome to our platform</h1>"
        };

        var response = await smtp2Go.SendEmailAsync(request);
        // response.Data.Succeeded == 1
    }
}

Managing Webhooks

// Create a webhook with Basic Auth (credentials embedded in URL)
var request = new WebhookCreateRequest
{
    WebhookUrl = "https://user:pass@api.yourdomain.com/webhooks/smtp2go",
    Events = [WebhookCreateEvent.Delivered, WebhookCreateEvent.Bounce]
};

var response = await smtp2Go.Webhooks.CreateAsync(request);

// List all webhooks
var webhooks = await smtp2Go.Webhooks.ListAsync();

// Delete a webhook
await smtp2Go.Webhooks.DeleteAsync(webhookId);

Receiving Webhook Callbacks

SMTP2GO sends HTTP POST requests to your registered webhook URL when email events occur. The WebhookCallbackPayload model deserializes the inbound payload:

[HttpPost("webhooks/smtp2go")]
public IActionResult HandleWebhook([FromBody] WebhookCallbackPayload payload)
{
    switch (payload.Event)
    {
        case WebhookCallbackEvent.Delivered:
            logger.LogInformation("Delivered to {Recipient}", payload.Recipient);
            break;

        case WebhookCallbackEvent.Bounce:
            logger.LogWarning("Bounce ({Type}) for {Recipient}: {Context}",
                payload.BounceType, payload.Recipient, payload.BounceContext);
            break;

        case WebhookCallbackEvent.SpamComplaint:
            logger.LogWarning("Spam complaint from {Recipient}", payload.Recipient);
            break;
    }

    return Ok();
}

Webhook Event Types

SMTP2GO uses different event names for subscriptions vs callback payloads:

Callback Payload Fields

Querying Statistics

var request = new EmailSummaryRequest
{
    StartDate = DateOnly.FromDateTime(DateTime.UtcNow.AddDays(-7)),
    EndDate = DateOnly.FromDateTime(DateTime.UtcNow)
};

var summary = await smtp2Go.Statistics.GetEmailSummaryAsync(request);

Features

• Email Sending - Send transactional emails with attachments, CC/BCC, custom headers, and inline images
• Webhook Management - Create, list, and delete webhook subscriptions for delivery events
• Webhook Callbacks - Strongly-typed models for receiving and processing webhook payloads
• Email Statistics - Query email delivery summaries and metrics
• Built-in Resilience - Production-grade HTTP pipeline with retry, circuit breaker, rate limiting, and timeouts
• Strongly Typed - Full request/response models with XML documentation
• Source-Generated Logging - Zero-reflection [LoggerMessage] for high-performance diagnostics
• DI Integration - First-class IServiceCollection registration with IHttpClientFactory

HTTP Resilience Pipeline

The AddSmtp2GoWithHttp registration includes a production-grade resilience pipeline:

Configuration Options

Supported Frameworks

All packages are strong-named for use in strong-named assemblies.

Development

Prerequisites

• .NET 10 SDK
• SMTP2GO account with API keys (for integration tests)

Building

dotnet build Smtp2Go.NET.slnx

Testing

# Unit tests (74 tests, no network required)
tests/Smtp2Go.NET.UnitTests/bin/Debug/net10.0/Smtp2Go.NET.UnitTests

# Integration tests (15 tests, requires API keys configured via user secrets)
tests/Smtp2Go.NET.IntegrationTests/bin/Debug/net10.0/Smtp2Go.NET.IntegrationTests

Note: xUnit v3 test projects are standalone executables.

Configuring Test Secrets

cd tests/Smtp2Go.NET.IntegrationTests
dotnet user-secrets set "Smtp2Go:ApiKey:Sandbox" "api-YOUR-SANDBOX-KEY"
dotnet user-secrets set "Smtp2Go:ApiKey:Live" "api-YOUR-LIVE-KEY"
dotnet user-secrets set "Smtp2Go:TestSender" "verified-sender@yourdomain.com"
dotnet user-secrets set "Smtp2Go:TestRecipient" "test@yourmailbox.com"

Or use the interactive setup script: pwsh -File scripts/setup-secrets.ps1

Project Structure

Smtp2Go.NET/
├── src/Smtp2Go.NET/                    # Library source
│   ├── Core/Smtp2GoResource.cs         # Base class (shared PostAsync)
│   ├── Models/                         # Request/response DTOs
│   │   ├── Email/                      # Email send models
│   │   ├── Statistics/                 # Statistics query models
│   │   └── Webhooks/                   # Webhook CRUD + payload models
│   ├── ISmtp2GoClient.cs              # Main client interface
│   ├── Smtp2GoClient.cs              # Main client implementation
│   └── ServiceCollectionExtensions.cs # DI registration
└── tests/
    ├── Smtp2Go.NET.UnitTests/         # 77 unit tests (Moq-based)
    └── Smtp2Go.NET.IntegrationTests/  # 15 integration tests (live API)

License

This project is licensed under the Apache 2.0 License.