Emailit 2.0.1

Emailit .NET

The official .NET SDK for the Emailit Email API.

Requirements

• .NET 8.0+

Installation

dotnet add package Emailit

Getting Started

using Emailit;
using Emailit.Options;
using Emailit.Resources;

var emailit = new EmailitClient("your_api_key");

Email email = emailit.Emails.Send(new EmailSendOptions
{
    From = "hello@yourdomain.com",
    To = new[] { "user@example.com" },
    Subject = "Hello from Emailit",
    Html = "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
});

Console.WriteLine(email.Id);     // em_abc123...
Console.WriteLine(email.Status); // pending

All service methods accept strongly-typed option classes and return typed resource objects (Email, Domain, Contact, etc.) with real properties.

Available Services

Usage

Emails

Send an email

Email email = emailit.Emails.Send(new EmailSendOptions
{
    From = "hello@yourdomain.com",
    To = new[] { "user@example.com" },
    Subject = "Hello from Emailit",
    Html = "<h1>Welcome!</h1>",
});

Console.WriteLine(email.Id);
Console.WriteLine(email.Status);

Send with a template

Email email = emailit.Emails.Send(new EmailSendOptions
{
    From = "hello@yourdomain.com",
    To = "user@example.com",
    Template = "welcome_email",
    Variables = new Dictionary<string, object?>
    {
        ["name"] = "John",
        ["company"] = "Acme",
    },
});

Send with attachments

Email email = emailit.Emails.Send(new EmailSendOptions
{
    From = "invoices@yourdomain.com",
    To = "customer@example.com",
    Subject = "Your Invoice",
    Html = "<p>Please find your invoice attached.</p>",
    Attachments = new List<EmailAttachment>
    {
        new EmailAttachment
        {
            Filename = "invoice.pdf",
            Content = Convert.ToBase64String(File.ReadAllBytes("invoice.pdf")),
            ContentType = "application/pdf",
        },
    },
});

Schedule an email

Email email = emailit.Emails.Send(new EmailSendOptions
{
    From = "reminders@yourdomain.com",
    To = "user@example.com",
    Subject = "Reminder",
    Html = "<p>Don't forget about tomorrow's meeting.</p>",
    ScheduledAt = "2026-01-10T09:00:00Z",
});

Send with tracking

Email email = emailit.Emails.Send(new EmailSendOptions
{
    From = "hello@yourdomain.com",
    To = new[] { "user@example.com" },
    Subject = "Tracked Email",
    Html = "<p>Hello!</p>",
    Tracking = new EmailTracking { Loads = true, Clicks = true },
});

Send from System.Net.Mail.MailMessage

using System.Net.Mail;

var message = new MailMessage("from@yourdomain.com", "to@example.com", "Hello", "<h1>Hi!</h1>")
{
    IsBodyHtml = true,
};
message.CC.Add("cc@example.com");
message.Attachments.Add(new Attachment("report.pdf"));

Email email = emailit.Emails.Send(message);

List emails

EmailitCollection<Email> list = emailit.Emails.List(new EmailListOptions { Page = 1, Limit = 10 });

foreach (Email email in list)
{
    Console.WriteLine($"{email.Id} - {email.Status}");
}

if (list.HasMore())
{
    Console.WriteLine("More pages available");
}

Get, cancel, and retry

Email email = emailit.Emails.Get("em_abc123");
emailit.Emails.Cancel("em_abc123");
emailit.Emails.Retry("em_abc123");

Get raw, attachments, body, meta

var raw = emailit.Emails.GetRaw("em_abc123");
var attachments = emailit.Emails.GetAttachments("em_abc123");
var body = emailit.Emails.GetBody("em_abc123");
var meta = emailit.Emails.GetMeta("em_abc123");

Domains

// Create
Domain domain = emailit.Domains.Create(new DomainCreateOptions
{
    Name = "example.com",
    TrackLoads = true,
    TrackClicks = true,
});

// Verify
emailit.Domains.Verify("dom_abc123");

// List
EmailitCollection<Domain> domains = emailit.Domains.List();

// Get
Domain domain = emailit.Domains.Get("dom_abc123");

// Update
emailit.Domains.Update("dom_abc123", new DomainUpdateOptions { TrackClicks = false });

// Delete
emailit.Domains.Delete("dom_abc123");

API Keys

// Create
ApiKey key = emailit.ApiKeys.Create(new ApiKeyCreateOptions
{
    Name = "Production Key",
    Scope = "sending",
});

Console.WriteLine(key.Key); // only available on create

// List
EmailitCollection<ApiKey> keys = emailit.ApiKeys.List();

// Get
ApiKey key = emailit.ApiKeys.Get("key_abc123");

// Update
emailit.ApiKeys.Update("key_abc123", new ApiKeyUpdateOptions { Name = "Updated Name" });

// Delete
emailit.ApiKeys.Delete("key_abc123");

Audiences

// Create
Audience audience = emailit.Audiences.Create(new AudienceCreateOptions { Name = "Newsletter" });

// List
EmailitCollection<Audience> audiences = emailit.Audiences.List();

// Get
Audience audience = emailit.Audiences.Get("aud_abc123");

// Update
emailit.Audiences.Update("aud_abc123", new AudienceUpdateOptions { Name = "Updated Newsletter" });

// Delete
emailit.Audiences.Delete("aud_abc123");

Subscribers

// Create
Subscriber subscriber = emailit.Subscribers.Create("aud_abc123", new SubscriberCreateOptions
{
    Email = "user@example.com",
    FirstName = "John",
    LastName = "Doe",
});

// List
EmailitCollection<Subscriber> subscribers = emailit.Subscribers.List("aud_abc123");

// Get
Subscriber subscriber = emailit.Subscribers.Get("aud_abc123", "sub_abc123");

// Update
emailit.Subscribers.Update("aud_abc123", "sub_abc123", new SubscriberUpdateOptions
{
    FirstName = "Jane",
});

// Delete
emailit.Subscribers.Delete("aud_abc123", "sub_abc123");

Templates

// Create
Template template = emailit.Templates.Create(new TemplateCreateOptions
{
    Name = "Welcome Email",
    Subject = "Welcome {{name}}",
    Html = "<h1>Hello {{name}}!</h1>",
});

// List
EmailitCollection<Template> templates = emailit.Templates.List();

// Get
Template template = emailit.Templates.Get("tpl_abc123");

// Update
emailit.Templates.Update("tpl_abc123", new TemplateUpdateOptions { Subject = "Updated Subject" });

// Publish
emailit.Templates.Publish("tpl_abc123");

// Delete
emailit.Templates.Delete("tpl_abc123");

Suppressions

// Create
Suppression suppression = emailit.Suppressions.Create(new SuppressionCreateOptions
{
    Email = "bounced@example.com",
    Type = "hard_bounce",
    Reason = "Mailbox does not exist",
});

// List
EmailitCollection<Suppression> suppressions = emailit.Suppressions.List();

// Get
Suppression suppression = emailit.Suppressions.Get("sup_abc123");

// Update
emailit.Suppressions.Update("sup_abc123", new SuppressionUpdateOptions { Reason = "Updated reason" });

// Delete
emailit.Suppressions.Delete("sup_abc123");

Email Verifications

EmailVerification result = emailit.EmailVerifications.Verify(new EmailVerificationVerifyOptions
{
    Email = "user@example.com",
});

Console.WriteLine(result.Status); // valid, invalid, risky, unknown
Console.WriteLine(result.Score);
Console.WriteLine(result.Risk);

Email Verification Lists

// Create
EmailVerificationList list = emailit.EmailVerificationLists.Create(new EmailVerificationListCreateOptions
{
    Name = "My List",
    Emails = new List<string> { "a@example.com", "b@example.com" },
});

// List
var lists = emailit.EmailVerificationLists.List();

// Get
EmailVerificationList list = emailit.EmailVerificationLists.Get("evl_abc123");

// Get results
var results = emailit.EmailVerificationLists.Results("evl_abc123");

// Export (XLSX)
var response = emailit.EmailVerificationLists.Export("evl_abc123");
File.WriteAllText("results.xlsx", response.Body);

Webhooks

// Create
Webhook webhook = emailit.Webhooks.Create(new WebhookCreateOptions
{
    Name = "My Webhook",
    Url = "https://example.com/webhook",
    AllEvents = true,
});

// List
EmailitCollection<Webhook> webhooks = emailit.Webhooks.List();

// Get
Webhook webhook = emailit.Webhooks.Get("wh_abc123");

// Update
emailit.Webhooks.Update("wh_abc123", new WebhookUpdateOptions
{
    Enabled = false,
});

// Delete
emailit.Webhooks.Delete("wh_abc123");

Contacts

// Create
Contact contact = emailit.Contacts.Create(new ContactCreateOptions
{
    Email = "user@example.com",
    FirstName = "John",
    LastName = "Doe",
    Audiences = new List<string> { "aud_abc123" },
});

// List
EmailitCollection<Contact> contacts = emailit.Contacts.List();

// Get
Contact contact = emailit.Contacts.Get("con_abc123");

// Update
emailit.Contacts.Update("con_abc123", new ContactUpdateOptions
{
    FirstName = "Jane",
});

// Delete
emailit.Contacts.Delete("con_abc123");

Events

// List
EmailitCollection<Event> events = emailit.Events.List(new EventListOptions
{
    Type = "email.delivered",
    Page = 1,
    Limit = 10,
});

// Get
Event evt = emailit.Events.Get("evt_abc123");

Webhook Verification

Verify incoming webhook signatures to ensure they're from Emailit:

using Emailit;
using Emailit.Events;

var rawBody = /* raw request body string */;
var signature = request.Headers["x-emailit-signature"];
var timestamp = request.Headers["x-emailit-timestamp"];
var secret = "your_webhook_secret";

try
{
    var evt = WebhookSignature.Verify(rawBody, signature, timestamp, secret);

    Console.WriteLine(evt.Type);    // e.g. "email.delivered"
    Console.WriteLine(evt.EventId); // e.g. "evt_abc123"

    switch (evt)
    {
        case EmailDelivered delivered:
            Console.WriteLine("Email delivered!");
            break;
        case EmailBounced bounced:
            Console.WriteLine("Email bounced!");
            break;
    }
}
catch (Emailit.Exceptions.ApiErrorException ex)
{
    Console.WriteLine($"Verification failed: {ex.Message}");
}

Supported Webhook Event Types

Error Handling

The SDK throws typed exceptions for different error scenarios:

using Emailit.Exceptions;
using Emailit.Options;

try
{
    Email email = emailit.Emails.Send(new EmailSendOptions
    {
        From = "hello@yourdomain.com",
        To = "user@example.com",
        Subject = "Hello",
        Html = "<p>Hi</p>",
    });
}
catch (AuthenticationException ex)
{
    // 401 - Invalid API key
    Console.WriteLine($"Auth error: {ex.Message}");
}
catch (InvalidRequestException ex)
{
    // 400, 404 - Bad request or not found
    Console.WriteLine($"Invalid request: {ex.Message}");
}
catch (UnprocessableEntityException ex)
{
    // 422 - Validation error
    Console.WriteLine($"Validation error: {ex.Message}");
}
catch (RateLimitException ex)
{
    // 429 - Rate limit exceeded
    Console.WriteLine($"Rate limited: {ex.Message}");
}
catch (ApiConnectionException ex)
{
    // Network/connection error
    Console.WriteLine($"Connection failed: {ex.Message}");
}
catch (ApiErrorException ex)
{
    // Other API errors
    Console.WriteLine($"API error ({ex.HttpStatus}): {ex.Message}");
    Console.WriteLine($"Body: {ex.HttpBody}");
}

All exceptions extend ApiErrorException and expose:

• HttpStatus - HTTP status code
• HttpBody - Raw response body
• JsonBody - Parsed JSON body (if available)
• HttpHeaders - Response headers

Configuration

// Basic
var emailit = new EmailitClient("your_api_key");

// Custom API base URL
var emailit = new EmailitClient("your_api_key", apiBase: "https://custom.api.com");

// Custom HttpClient
var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
var emailit = new EmailitClient("your_api_key", httpClient: httpClient);

License

MIT