.NET SDK

The official .NET SDK for Veil Mail with idiomatic C# patterns.

  • Full async/await support with CancellationToken
  • NuGet package for easy installation
  • Constant-time HMAC webhook verification
  • .NET Standard 2.1+ compatible
  • Custom HttpClient support for DI

Installation

dotnet add package VeilMail

Quick Start

Program.cs
using VeilMail;

var client = new VeilMailClient("veil_live_xxxxx");

var email = await client.Emails.SendAsync(new Dictionary<string, object?>
{
    ["from"] = "hello@yourdomain.com",
    ["to"] = "user@example.com",
    ["subject"] = "Hello from .NET!",
    ["html"] = "<h1>Welcome!</h1>",
});

Console.WriteLine(email["id"]);     // email_xxxxx
Console.WriteLine(email["status"]); // queued

Resources

The client exposes the same resources as the Node.js SDK:

ResourceDescription
client.EmailsSend, batch send, list, get, cancel, update emails
client.DomainsCreate, verify, update, list, delete domains
client.TemplatesCreate, update, preview, list, delete templates
client.AudiencesManage audiences and subscribers
client.CampaignsCreate, schedule, send, pause, resume, cancel campaigns
client.WebhooksManage webhook endpoints, test, rotate secrets
client.TopicsManage subscription topics and preferences
client.PropertiesManage contact property definitions and values

Error Handling

ErrorHandling.cs
using VeilMail.Exceptions;

try
{
    await client.Emails.SendAsync(new Dictionary<string, object?>
    {
        ["from"] = "hello@yourdomain.com",
        ["to"] = "user@example.com",
        ["subject"] = "Hello",
        ["html"] = "<p>Hi!</p>",
    });
}
catch (RateLimitException e)
{
    Console.WriteLine($"Rate limited. Retry after {e.RetryAfter}s");
}
catch (PiiDetectedException e)
{
    Console.WriteLine($"PII detected: {string.Join(", ", e.PiiTypes)}");
}
catch (ValidationException e)
{
    Console.WriteLine($"Validation error: {e.Message}");
}
catch (AuthenticationException)
{
    Console.WriteLine("Invalid API key");
}
catch (VeilMailException e)
{
    Console.WriteLine($"API error: {e.Message} (code: {e.ErrorCode})");
}

Webhook Verification

Use the built-in utility to verify webhook signatures in ASP.NET:

WebhookController.cs
using VeilMail;

[HttpPost("webhooks/veilmail")]
public IActionResult HandleWebhook()
{
    using var reader = new StreamReader(Request.Body);
    var body = reader.ReadToEnd();
    var signature = Request.Headers["X-Signature-Hash"].FirstOrDefault() ?? "";

    if (!Webhook.VerifySignature(body, signature, _webhookSecret))
    {
        return Unauthorized();
    }

    var payload = JsonSerializer.Deserialize<Dictionary<string, object>>(body);
    // Process event...

    return Ok();
}

Required Scopes

The .NET SDK uses the same API scopes as the Authentication system. See the Node.js SDK documentation for the full scope reference.