Email client

Full reference for the Paubox C# SDK Email API client: sending messages, bulk sending, delivery tracking, dynamic templates, and error handling.

Instantiation

// Direct credentials
var emailLib = new EmailLibrary("YOUR_API_KEY", "YOUR_USERNAME");

// IConfiguration (ASP.NET Core)
var emailLib = new EmailLibrary(configuration);

See Authentication for both approaches. Use IEmailLibrary for dependency injection.

Building a message

var message = new Message
{
    Recipients = new[] { "[e-mail]" },          // required
    Cc         = new[] { "[e-mail]" },        // optional
    Bcc        = new[] { "[e-mail]" },          // optional
    Header = new Header
    {
        From    = "[e-mail]",               // required
        Subject = "Your results are ready",              // required
        ReplyTo = "[e-mail]",              // optional
        CustomHeaders = new Dictionary<string, string>   // optional
        {
            { "X-Custom-Header", "value" }
        }
    },
    Content = new Content
    {
        PlainText = "Plain text body.",                  // at least one required
        HtmlText  = "<p>HTML body.</p>"                  // optional; auto base64-encoded
    },
    Attachments          = new List<Attachment> { attachment },  // optional
    AllowNonTLS          = false,                        // optional; default false
    ForceSecureNotification = "true"                     // optional; "true" or "false"
};

Attachments

byte[] fileBytes = File.ReadAllBytes("report.pdf");

var attachment = new Attachment
{
    FileName    = "report.pdf",
    ContentType = "application/pdf",
    Content     = Convert.ToBase64String(fileBytes)
};

message.Attachments = new List<Attachment> { attachment };

Send a message

SendMessageResponse response = emailLib.SendMessage(message);

Console.WriteLine("Tracking ID: " + response.SourceTrackingId);

The SendMessageResponse includes:

Property	Description
SourceTrackingId	Use to check delivery status
Data	Raw response data
Errors	List of Error objects if the request failed

Send bulk messages

Send up to 50 messages in a single API call. Each message gets its own tracking ID.

var messages = new[]
{
    new Message
    {
        Recipients = new[] { "[e-mail]" },
        Header  = new Header { From = "[e-mail]", Subject = "Hi Alice" },
        Content = new Content { PlainText = "Hello Alice" }
    },
    new Message
    {
        Recipients = new[] { "[e-mail]" },
        Header  = new Header { From = "[e-mail]", Subject = "Hi Bob" },
        Content = new Content { PlainText = "Hello Bob" }
    }
};

SendBulkMessagesResponse bulkResponse = emailLib.SendBulkMessages(messages);

foreach (var msg in bulkResponse.Messages)
{
    Console.WriteLine($"Tracking ID: {msg.SourceTrackingId}");
}

Check delivery status

GetEmailDispositionResponse disposition =
    emailLib.GetEmailDisposition(response.SourceTrackingId);

foreach (var delivery in disposition.Data.Message.MessageDeliveries)
{
    Console.WriteLine($"{delivery.Recipient} → {delivery.Status.DeliveryStatus}");
}

Common DeliveryStatus values: delivered, opened, failed, pending.

Dynamic templates

Templates use Handlebars syntax ({{variable_name}}).

Create a template

DynamicTemplateResponse created = emailLib.CreateDynamicTemplate(
    templateName: "appointment-confirmation",
    templatePath: @"C:\templates\appointment.html"
);

List templates

List<DynamicTemplateSummary> templates = emailLib.ListDynamicTemplates();
foreach (var t in templates)
    Console.WriteLine($"{t.Id}: {t.Name}");

Get a template

GetDynamicTemplateResponse tmpl = emailLib.GetDynamicTemplate(templateId);

Update a template

DynamicTemplateResponse updated = emailLib.UpdateDynamicTemplate(
    templateId:   123,
    templateName: "appointment-confirmation-v2",
    templatePath: @"C:\templates\appointment-v2.html"
);

Delete a template

DeleteDynamicTemplateResponse deleted = emailLib.DeleteDynamicTemplate(templateId);

Send a templated message

var templatedMsg = new TemplatedMessage
{
    Recipients    = new[] { "[e-mail]" },
    Header        = new Header { From = "[e-mail]", Subject = "Your appointment" },
    TemplateName  = "appointment-confirmation",
    TemplateValues = new Dictionary<string, object>
    {
        { "first_name", "Jane" },
        { "date",       "2024-03-15" },
        { "time",       "2:00 PM" }
    }
};

SendMessageResponse response = emailLib.SendTemplatedMessage(templatedMsg);

Error handling

All methods throw SystemException on API errors. The exception message contains the raw JSON response body:

try
{
    SendMessageResponse response = emailLib.SendMessage(message);
}
catch (SystemException ex)
{
    // ex.Message contains the raw JSON error response
    Console.WriteLine("API error: " + ex.Message);

    // Parse if needed:
    // var error = JsonSerializer.Deserialize<ErrorResponse>(ex.Message);
}