Dinocollab.EmailTemplate.Sdk 1.0.0

Dinocollab Email Template SDK

A .NET SDK for interacting with Dinocollab Email Template Sender API.

Features

• Send simple emails without templates
• Send emails using templates by code
• Queue emails for background processing
• Schedule emails for future delivery
• Send bulk emails
• Monitor job status
• Manage placeholders
• Built-in error handling and retry mechanisms
• Support for dependency injection

Installation

Add the NuGet package to your project:

dotnet add package Dinocollab.EmailTemplate.Sdk

Quick Start

Basic Usage

using Dinocollab.EmailTemplate.Sdk;
using Dinocollab.EmailTemplate.Sdk.Models;

// Create SDK client
var client = EmailTemplateSdk.CreateClient(
    baseUrl: "https://your-api-endpoint.com",
    apiKey: "your-api-key"
);

// Send a simple email
var simpleEmailRequest = new SendSimpleEmailRequest
{
    To = "recipient@example.com",
    Subject = "Test Email",
    HtmlContent = "<h1>Hello World!</h1>",
    TextContent = "Hello World!",
    SenderAccountCode = "default-sender"
};

var result = await client.Email.SendSimpleEmailAsync(simpleEmailRequest);

Using Builder Pattern

var client = EmailTemplateSdk.CreateBuilder()
    .WithBaseUrl("https://your-api-endpoint.com")
    .WithApiKey("your-api-key")
    .WithDefaultSenderAccountCode("default-sender")
    .WithTimeout(60)
    .Build();

Dependency Injection

// In Program.cs or Startup.cs
services.AddEmailTemplateSdk(options =>
{
    options.BaseUrl = "https://your-api-endpoint.com";
    options.ApiKey = "your-api-key";
    options.DefaultSenderAccountCode = "default-sender";
    options.TimeoutSeconds = 60;
});

// In your controller or service
public class EmailService
{
    private readonly IEmailTemplateSdkClient _emailClient;

    public EmailService(IEmailTemplateSdkClient emailClient)
    {
        _emailClient = emailClient;
    }

    public async Task SendWelcomeEmail(string email, string name)
    {
        var request = new SendTemplateEmailByCodeRequest
        {
            To = email,
            TemplateCode = "welcome-email",
            Placeholders = new Dictionary<string, string>
            {
                ["name"] = name,
                ["date"] = DateTime.Now.ToString("yyyy-MM-dd")
            }
        };

        var result = await _emailClient.Email.SendTemplateEmailByCodeAsync(request);
    }
}

Email Operations

Send Template Email

var templateRequest = new SendTemplateEmailByCodeRequest
{
    To = "recipient@example.com",
    TemplateCode = "welcome-template",
    Placeholders = new Dictionary<string, string>
    {
        ["name"] = "John Doe",
        ["company"] = "Acme Corp"
    },
    SenderAccountCode = "welcome-sender"
};

var result = await client.Email.SendTemplateEmailByCodeAsync(templateRequest);

Queue Email for Background Processing

var queueRequest = new SendSimpleEmailRequest
{
    To = "recipient@example.com",
    Subject = "Queued Email",
    HtmlContent = "<p>This email was queued for processing.</p>"
};

var result = await client.Email.QueueSimpleEmailAsync(queueRequest);
Console.WriteLine($"Job ID: {result.JobId}");

Schedule Email

var scheduleRequest = new ScheduleTemplateEmailRequest
{
    To = "recipient@example.com",
    TemplateCode = "reminder-template",
    ScheduledTime = DateTime.UtcNow.AddHours(24),
    Placeholders = new Dictionary<string, string>
    {
        ["event"] = "Meeting Tomorrow"
    }
};

var result = await client.Email.ScheduleTemplateEmailAsync(scheduleRequest);

Send Bulk Emails

var bulkRequest = new BulkTemplateEmailRequest
{
    TemplateCode = "newsletter",
    DefaultPlaceholders = new Dictionary<string, string>
    {
        ["newsletter_date"] = DateTime.Now.ToString("MMMM yyyy")
    },
    Recipients = new List<BulkEmailRecipient>
    {
        new BulkEmailRecipient
        {
            Email = "user1@example.com",
            Placeholders = new Dictionary<string, string> { ["name"] = "User 1" }
        },
        new BulkEmailRecipient
        {
            Email = "user2@example.com",
            Placeholders = new Dictionary<string, string> { ["name"] = "User 2" }
        }
    }
};

var result = await client.Email.BulkTemplateEmailAsync(bulkRequest);

Monitor Job Status

var jobStatus = await client.Email.GetJobStatusAsync("job-id-here");
Console.WriteLine($"Job State: {jobStatus.State}");
Console.WriteLine($"Created At: {jobStatus.CreatedAt}");

Placeholder Operations

Get All Placeholders

var placeholders = await client.Placeholder.GetPlaceholdersAsync();
foreach (var placeholder in placeholders)
{
    Console.WriteLine($"{placeholder.Key}: {placeholder.Description}");
}

Get Placeholders by Category

var userPlaceholders = await client.Placeholder.GetPlaceholdersByCategoryAsync("user");

Get Specific Placeholder

var placeholder = await client.Placeholder.GetPlaceholderAsync("user.name");
if (placeholder != null)
{
    Console.WriteLine($"Description: {placeholder.Description}");
    Console.WriteLine($"Default Value: {placeholder.DefaultValue}");
}

Error Handling

The SDK provides specific exception types for different error scenarios:

try
{
    var result = await client.Email.SendSimpleEmailAsync(request);
}
catch (AuthenticationException ex)
{
    // Handle authentication errors (401)
    Console.WriteLine($"Authentication failed: {ex.Message}");
}
catch (ValidationException ex)
{
    // Handle validation errors (400)
    Console.WriteLine($"Validation failed: {ex.Message}");
}
catch (ApiRequestException ex)
{
    // Handle other API errors
    Console.WriteLine($"API error ({ex.StatusCode}): {ex.Message}");
}
catch (EmailTemplateSdkException ex)
{
    // Handle general SDK errors
    Console.WriteLine($"SDK error: {ex.Message}");
}

Configuration Options

public class EmailTemplateSdkOptions
{
    public string BaseUrl { get; set; } = "";
    public string ApiKey { get; set; } = "";
    public int TimeoutSeconds { get; set; } = 30;
    public int MaxRetryAttempts { get; set; } = 3;
    public string? DefaultSenderAccountCode { get; set; }
}

API Endpoints

The SDK interacts with the following API endpoints:

• POST /api/EmailApi/send-simple - Send simple email
• POST /api/EmailApi/send-template-by-code - Send template email
• POST /api/EmailApi/queue-simple - Queue simple email
• POST /api/EmailApi/schedule-template - Schedule template email
• POST /api/EmailApi/bulk-template - Send bulk emails
• GET /api/EmailApi/job-status/{jobId} - Get job status
• GET /api/PlaceholderApi - Get all placeholders
• GET /api/PlaceholderApi/category/{category} - Get placeholders by category
• GET /api/PlaceholderApi/{key} - Get specific placeholder

Requirements

• .NET Standard 2.0 or higher
• Valid API key for the Email Template Sender service

License

[Add your license information here]