# Mailtrap .NET Client

## Introduction

The Mailtrap .NET Client is the official SDK for integrating .NET applications with the Mailtrap API v2.0. Mailtrap is a comprehensive email testing and delivery platform that provides email sandbox functionality for development and testing, along with production email sending capabilities. This client library enables developers to send transactional and bulk emails, manage email templates, work with testing inboxes, manage contacts and mailing lists, and access account management features through a clean, strongly-typed C# API.

The library is built on .NET Standard 2.0, making it compatible with a wide range of .NET implementations including .NET Core, .NET 5+, and .NET Framework 4.6.1+. It provides a fluent API for constructing email requests, comprehensive error handling through typed exceptions, built-in request validation, and seamless integration with ASP.NET Core's dependency injection container. The SDK supports all major Mailtrap features including email sending (transactional and bulk streams), template management, sandbox testing, domain verification, inbox management, contacts management with custom fields and lists, bulk import/export operations, event tracking, suppression list management, and account administration.

## API Documentation

### Send a Simple Email

Send a transactional or bulk email using the default configured email client with basic text content and recipients.

```csharp
using Mailtrap;
using Mailtrap.Emails.Requests;
using Mailtrap.Emails.Responses;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

// Setup DI container
HostApplicationBuilder hostBuilder = Host.CreateApplicationBuilder(args);

hostBuilder.Services.AddMailtrapClient(options =>
{
    options.ApiToken = "your-api-token-here";
});

using IHost host = hostBuilder.Build();
IMailtrapClient mailtrapClient = host.Services.GetRequiredService<IMailtrapClient>();

// Create and send email using fluent API
SendEmailRequest request = SendEmailRequest
    .Create()
    .From("john.doe@demomailtrap.com", "John Doe")
    .To("hero.bill@galaxy.net")
    .Subject("Invitation to Earth")
    .Text("Dear Bill,\n\nIt will be a great pleasure to see you on our blue planet next weekend.\n\nBest regards, John.");

try
{
    SendEmailResponse response = await mailtrapClient.Email().Send(request);
    string messageId = response.MessageIds.FirstOrDefault();
    Console.WriteLine($"Email sent successfully. Message ID: {messageId}");
}
catch (MailtrapException ex)
{
    Console.WriteLine($"Mailtrap API error: {ex.Message}");
}
```

### Send Email with Multiple Recipients and HTML Body

Send an email with multiple recipient types (To, Cc, Bcc), HTML content, custom headers, and custom variables.

```csharp
using Mailtrap.Emails.Requests;
using Mailtrap.Emails.Models;

SendEmailRequest request = SendEmailRequest.Create();

// Configure sender and recipients
request.From("john.doe@demomailtrap.com", "John Doe");
request.ReplyTo("info@domain.com");

request.To("hero.bill@galaxy.net");
request.To("steel.rat@galaxy.net", "James");

var vipEmail = new EmailAddress("star.lord@galaxy.net");
request.Cc(vipEmail);

request.Bcc(
    new EmailAddress("first@domain.com"),
    new EmailAddress("second@domain.com"));

// Set content
request.Subject("Invitation to Earth");
request.Html(
    "<h2>Greetings, Bill!</h2>" +
    "<p>It will be a great pleasure to see you on our blue planet next weekend.</p>" +
    "<p>Regards,<br/>John</p>");
request.Text("Dear Bill,\n\nIt will be a great pleasure to see you on our blue planet next weekend.\n\nBest regards, John.");

// Add metadata
request.Category("Invitation");
request.CustomVariable("campaign_id", "summer_2024");
request.Header("X-Custom-Header", "Custom Value");

// Send the email
SendEmailResponse response = await mailtrapClient.Email().Send(request);
```

### Send Email with Attachments

Attach files to an email as either regular attachments or inline content with content IDs for embedding in HTML.

```csharp
using System.Net.Mime;
using Mailtrap.Core.Models;

SendEmailRequest request = SendEmailRequest
    .Create()
    .From("john.doe@demomailtrap.com", "John Doe")
    .To("hero.bill@galaxy.net")
    .Subject("Documents Attached")
    .Html("<p>Please find the attached documents.</p><img src='cid:logo_1' />");

// Attach a PDF file
var pdfPath = @"C:\files\preview.pdf";
var pdfBytes = File.ReadAllBytes(pdfPath);
var pdfContent = Convert.ToBase64String(pdfBytes);

request.Attach(
    content: pdfContent,
    fileName: "preview.pdf",
    disposition: DispositionType.Attachment,
    mimeType: MediaTypeNames.Application.Pdf);

// Attach an inline image with content ID
var imagePath = @"C:\files\logo.png";
var imageBytes = File.ReadAllBytes(imagePath);
var imageContent = Convert.ToBase64String(imageBytes);

request.Attach(
    content: imageContent,
    fileName: "logo.png",
    disposition: DispositionType.Inline,
    mimeType: MediaTypeNames.Image.Png,
    contentId: "logo_1");

SendEmailResponse response = await mailtrapClient.Email().Send(request);
```

### Send Email Using Template

Send an email using a pre-configured email template with dynamic variables instead of specifying subject and body.

```csharp
SendEmailRequest request = SendEmailRequest
    .Create()
    .From("john.doe@demomailtrap.com", "John Doe")
    .To("hero.bill@galaxy.net")
    .Template("60dca11e-0bc2-42ea-91a8-5ff196acb3f9")
    .TemplateVariables(new Dictionary<string, string>
    {
        { "name", "Bill" },
        { "sender", "John" },
        { "event_date", "Next Weekend" }
    });

SendEmailResponse response = await mailtrapClient.Email().Send(request);
Console.WriteLine($"Template email sent: {response.Success}");
```

### Send Batch Emails

Send multiple emails in a single API request with a shared base configuration and individual message customization.

```csharp
using Mailtrap.Emails.Requests;
using Mailtrap.Emails.Responses;
using Mailtrap.Emails.Models;

// Define base configuration shared by all emails
var baseRequest = new EmailRequest
{
    From = new EmailAddress("john.doe@galaxy.net", "John Doe"),
    ReplyTo = new EmailAddress("noreply@galaxy.net")
};

// Create individual email requests
var emails = new List<SendEmailRequest>
{
    SendEmailRequest
        .Create()
        .To("hero.bill@galaxy.net")
        .Subject("Personal Message")
        .Text("Hello Bill!"),

    SendEmailRequest
        .Create()
        .To("star.lord@galaxy.net")
        .Subject("Important Update")
        .Text("Hello Star Lord!")
};

// Create and send batch request
var batchRequest = new BatchEmailRequest
{
    Base = baseRequest,
    Requests = emails
};

BatchEmailResponse response = await mailtrapClient.BatchEmail().Send(batchRequest);

// Process results
foreach (BatchSendEmailResponse messageResponse in response.Responses)
{
    if (messageResponse.Success)
    {
        Console.WriteLine($"Email sent successfully. IDs: {string.Join(", ", messageResponse.MessageIds)}");
    }
    else
    {
        Console.WriteLine($"Email failed. Errors: {string.Join(", ", messageResponse.Errors)}");
    }
}
```

### Send to Specific Stream (Transactional or Bulk)

Explicitly specify whether to send emails through the transactional or bulk stream regardless of default configuration.

```csharp
// Send via transactional stream
SendEmailRequest transactionalEmail = SendEmailRequest
    .Create()
    .From("notifications@example.com")
    .To("user@example.com")
    .Subject("Password Reset")
    .Text("Click here to reset your password.");

SendEmailResponse transactionalResponse = await mailtrapClient.Transactional().Send(transactionalEmail);

// Send via bulk stream
SendEmailRequest bulkEmail = SendEmailRequest
    .Create()
    .From("marketing@example.com")
    .To("subscriber@example.com")
    .Subject("Monthly Newsletter")
    .Html("<h1>This Month's Updates</h1><p>Check out our latest features...</p>");

SendEmailResponse bulkResponse = await mailtrapClient.Bulk().Send(bulkEmail);

// Send to testing inbox
long testInboxId = 12345;
SendEmailRequest testEmail = SendEmailRequest
    .Create()
    .From("test@example.com")
    .To("recipient@example.com")
    .Subject("Test Email")
    .Text("This is a test.");

SendEmailResponse testResponse = await mailtrapClient.Test(testInboxId).Send(testEmail);
```

### Validate Email Request Before Sending

Validate email request data before sending to catch validation errors early and provide detailed error messages.

```csharp
using Mailtrap.Core.Validation;

SendEmailRequest request = SendEmailRequest
    .Create()
    .From("john.doe@demomailtrap.com", "John Doe")
    .To("hero.bill@galaxy.net")
    .Subject("Test Email")
    .Text("Test content");

// Validate the request
ValidationResult validationResult = request.Validate();

if (!validationResult.IsValid)
{
    Console.WriteLine("Email request validation failed:");
    Console.WriteLine(validationResult.ToString("\n"));

    foreach (var error in validationResult.Errors)
    {
        Console.WriteLine($"- {error.PropertyName}: {error.ErrorMessage}");
    }
}
else
{
    SendEmailResponse response = await mailtrapClient.Email().Send(request);
    Console.WriteLine("Email sent successfully");
}
```

### Manage Testing Inboxes

Create, retrieve, update, and delete testing inboxes for email sandbox functionality.

```csharp
using Mailtrap.Inboxes;
using Mailtrap.Inboxes.Models;
using Mailtrap.Inboxes.Requests;

long accountId = 12345;
long projectId = 54321;

IAccountResource accountResource = mailtrapClient.Account(accountId);
IInboxCollectionResource inboxesResource = accountResource.Inboxes();

// Get all inboxes
IList<Inbox> inboxes = await inboxesResource.GetAll();

// Create a new inbox
var createRequest = new CreateInboxRequest(projectId, "My Test Inbox");
Inbox newInbox = await inboxesResource.Create(createRequest);
Console.WriteLine($"Created inbox: {newInbox.Name} with ID: {newInbox.Id}");

// Get specific inbox details
IInboxResource inboxResource = accountResource.Inbox(newInbox.Id);
Inbox inboxDetails = await inboxResource.GetDetails();

// Update inbox
var updateRequest = new UpdateInboxRequest
{
    Name = "Updated Inbox Name"
};
Inbox updatedInbox = await inboxResource.Update(updateRequest);

// Mark all messages as read
await inboxResource.MarkAsRead();

// Reset credentials
Inbox resetInbox = await inboxResource.ResetCredentials();

// Reset email address
Inbox newAddressInbox = await inboxResource.ResetEmailAddress();

// Delete inbox
Inbox deletedInbox = await inboxResource.Delete();
Console.WriteLine($"Deleted inbox: {deletedInbox.Name}");
```

### Manage Testing Messages

Retrieve, update, delete, and forward testing messages in sandbox inboxes with support for spam analysis and content extraction.

```csharp
using Mailtrap.TestingMessages;
using Mailtrap.TestingMessages.Models;
using Mailtrap.TestingMessages.Requests;

long accountId = 12345;
long inboxId = 67890;
long messageId = 111222;

IAccountResource accountResource = mailtrapClient.Account(accountId);
ITestingMessageCollectionResource messagesResource = accountResource.TestingMessages(inboxId);

// Get all messages in inbox
IList<TestingMessage> messages = await messagesResource.GetAll();

// Get specific message details
ITestingMessageResource messageResource = accountResource.TestingMessage(inboxId, messageId);
TestingMessage message = await messageResource.GetDetails();

// Get message bodies
string textBody = await messageResource.GetTextBody();
string htmlBody = await messageResource.GetHtmlBody();
string htmlSource = await messageResource.GetHtmlSource();

// Get message in different formats
string rawMessage = await messageResource.AsRaw();
string emlMessage = await messageResource.AsEml();

// Get message headers
TestingMessageHeaders headers = await messageResource.GetHeaders();

// Get spam report
TestingMessageSpamReport spamReport = await messageResource.GetSpamReport();
Console.WriteLine($"Spam score: {spamReport.Score}");

// Get HTML analysis
TestingMessageHtmlReport htmlReport = await messageResource.GetHtmlAnalysisReport();

// Update message (mark as read/unread)
var updateRequest = new UpdateTestingMessageRequest { IsRead = true };
TestingMessage updatedMessage = await messageResource.Update(updateRequest);

// Forward message to confirmed email
var forwardRequest = new ForwardTestingMessageRequest("verified@example.com");
ForwardTestingMessageResponse forwardResponse = await messageResource.Forward(forwardRequest);

// Delete message
TestingMessage deletedMessage = await messageResource.Delete();
```

### Manage Projects

Create, retrieve, update, and delete projects that contain testing inboxes.

```csharp
using Mailtrap.Projects;
using Mailtrap.Projects.Models;
using Mailtrap.Projects.Requests;
using Mailtrap.Projects.Responses;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);

// Get all projects
IProjectCollectionResource projectsResource = accountResource.Projects();
IList<Project> projects = await projectsResource.GetAll();

// Create new project
var createRequest = new CreateProjectRequest("My New Project");
Project newProject = await projectsResource.Create(createRequest);
Console.WriteLine($"Created project: {newProject.Name} with ID: {newProject.Id}");

// Get specific project details
IProjectResource projectResource = accountResource.Project(newProject.Id);
Project projectDetails = await projectResource.GetDetails();

// Update project
var updateRequest = new UpdateProjectRequest
{
    Name = "Updated Project Name"
};
Project updatedProject = await projectResource.Update(updateRequest);

// Delete project (deletes all associated inboxes)
DeleteProjectResponse deleteResponse = await projectResource.Delete();
Console.WriteLine($"Project deleted: {deleteResponse.Success}");
```

### Manage Sending Domains

Add, verify, and manage domains for production email sending with DNS record verification.

```csharp
using Mailtrap.SendingDomains;
using Mailtrap.SendingDomains.Models;
using Mailtrap.SendingDomains.Requests;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);

// Get all sending domains
ISendingDomainCollectionResource domainsResource = accountResource.SendingDomains();
IList<SendingDomain> domains = await domainsResource.GetAll();

// Create new sending domain
var createRequest = new CreateSendingDomainRequest("example.com");
SendingDomain newDomain = await domainsResource.Create(createRequest);
Console.WriteLine($"Domain created: {newDomain.Name}");
Console.WriteLine($"Status: {newDomain.Status}");

// Display DNS records that need to be configured
foreach (var record in newDomain.DnsRecords)
{
    Console.WriteLine($"Type: {record.Type}, Name: {record.Hostname}, Value: {record.Value}");
}

// Get specific domain details
ISendingDomainResource domainResource = accountResource.SendingDomain(newDomain.Id);
SendingDomain domainDetails = await domainResource.GetDetails();

// Send setup instructions to email
var instructionsRequest = new SendingDomainInstructionsRequest("admin@example.com");
await domainResource.SendInstructions(instructionsRequest);

// Delete domain
await domainResource.Delete();
Console.WriteLine("Domain deleted successfully");
```

### Manage Contacts

Create, retrieve, update, and delete contacts for email campaigns and mailing list management.

```csharp
using Mailtrap.Contacts;
using Mailtrap.Contacts.Models;
using Mailtrap.Contacts.Requests;
using Mailtrap.Contacts.Responses;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);
IContactCollectionResource contactsResource = accountResource.Contacts();

// Create a new contact with custom fields
var createContactRequest = new CreateContactRequest("john.doe@example.com");
createContactRequest.Fields.Add("first_name", "John");
createContactRequest.Fields.Add("last_name", "Doe");
createContactRequest.Fields.Add("company", "Acme Inc");
CreateContactResponse createResponse = await contactsResource.Create(createContactRequest);
Contact newContact = createResponse.Contact;
Console.WriteLine($"Created contact: {newContact.Email} with ID: {newContact.Id}");

// Get specific contact details
IContactResource contactResource = accountResource.Contact(newContact.Id);
ContactResponse contactResponse = await contactResource.GetDetails();
Contact contactDetails = contactResponse.Contact;
Console.WriteLine($"Contact status: {contactDetails.Status}");

// Update contact
var updateContactRequest = new UpdateContactRequest("john.doe.updated@example.com");
updateContactRequest.Fields.Add("first_name", "Jonathan");
UpdateContactResponse updateResponse = await contactResource.Update(updateContactRequest);
Contact updatedContact = updateResponse.Contact;
Console.WriteLine($"Updated contact email to: {updatedContact.Email}");

// Delete contact
await contactResource.Delete();
Console.WriteLine("Contact deleted successfully");
```

### Manage Contact Lists

Create and manage contact lists for organizing contacts into groups for targeted campaigns.

```csharp
using Mailtrap.ContactLists;
using Mailtrap.ContactLists.Models;
using Mailtrap.ContactLists.Requests;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);
IContactCollectionResource contactsResource = accountResource.Contacts();

// Get resource for contact lists collection
IContactListCollectionResource contactListsResource = contactsResource.Lists();

// Get all contact lists
IList<ContactList> contactLists = await contactListsResource.GetAll();
Console.WriteLine($"Found {contactLists.Count} contact lists");

// Create a new contact list
var createRequest = new ContactListRequest("Newsletter Subscribers");
ContactList newList = await contactListsResource.Create(createRequest);
Console.WriteLine($"Created list: {newList.Name} with ID: {newList.Id}");

// Get specific contact list details
IContactListResource contactListResource = contactsResource.List(newList.Id);
ContactList listDetails = await contactListResource.GetDetails();
Console.WriteLine($"List has {listDetails.ContactsCount} contacts");

// Update contact list
var updateRequest = new ContactListRequest("Premium Newsletter Subscribers");
ContactList updatedList = await contactListResource.Update(updateRequest);
Console.WriteLine($"Updated list name to: {updatedList.Name}");

// Delete contact list
await contactListResource.Delete();
Console.WriteLine("Contact list deleted successfully");
```

### Manage Contact Fields

Create and manage custom contact fields for storing additional contact information beyond email address.

```csharp
using Mailtrap.ContactFields;
using Mailtrap.ContactFields.Models;
using Mailtrap.ContactFields.Requests;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);
IContactCollectionResource contactsResource = accountResource.Contacts();

// Get resource for contact fields collection
IContactFieldCollectionResource contactFieldsResource = contactsResource.Fields();

// Get all contact fields
IList<ContactField> contactFields = await contactFieldsResource.GetAll();

// Create a new contact field
var createRequest = new CreateContactFieldRequest(
    name: "Company Name",
    mergeTag: "company_name",
    dataType: ContactFieldDataType.Text);
ContactField newField = await contactFieldsResource.Create(createRequest);
Console.WriteLine($"Created field: {newField.Name} with merge tag: {newField.MergeTag}");

// Get specific contact field details
IContactFieldResource contactFieldResource = contactsResource.Field(newField.Id);
ContactField fieldDetails = await contactFieldResource.GetDetails();

// Update contact field
var updateRequest = new UpdateContactFieldRequest(
    name: "Organization Name",
    mergeTag: "org_name");
ContactField updatedField = await contactFieldResource.Update(updateRequest);
Console.WriteLine($"Updated field to: {updatedField.Name}");

// Delete contact field
await contactFieldResource.Delete();
Console.WriteLine("Contact field deleted successfully");
```

### Bulk Import Contacts

Import multiple contacts in a single operation for efficient bulk contact creation.

```csharp
using Mailtrap.ContactImports;
using Mailtrap.ContactImports.Models;
using Mailtrap.ContactImports.Requests;
using Mailtrap.Contacts.Requests;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);
IContactCollectionResource contactsResource = accountResource.Contacts();

// Get resource for contact imports
IContactImportCollectionResource contactImportsResource = contactsResource.Imports();

// Prepare list of contacts to import
var contactImportList = new List<ContactImportRequest>
{
    new("alice@example.com"),
    new("bob@example.com"),
    new("charlie@example.com")
};

// Create contact import request
var importRequest = new CreateContactImportRequest(contactImportList);

// Import contacts in bulk
ContactImport importResponse = await contactImportsResource.Create(importRequest);
Console.WriteLine($"Created contact import with ID: {importResponse.Id}");

// Get resource for specific contact import
IContactImportResource contactImportResource = contactsResource.Import(importResponse.Id);

// Get details of specific contact import
ContactImport importDetails = await contactImportResource.GetDetails();
Console.WriteLine($"Import status: {importDetails.Status}");
Console.WriteLine($"Created contacts: {importDetails.CreatedContactsCount}");
Console.WriteLine($"Updated contacts: {importDetails.UpdatedContactsCount}");
Console.WriteLine($"Over limit: {importDetails.ContactsOverLimitCount}");

if (importDetails.Status == ContactImportStatus.Failed)
{
    Console.WriteLine("Import failed!");
}
```

### Export Contacts

Export contacts based on filters for backup, analysis, or migration purposes.

```csharp
using Mailtrap.ContactExports;
using Mailtrap.ContactExports.Models;
using Mailtrap.ContactExports.Requests;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);
IContactCollectionResource contactsResource = accountResource.Contacts();

// Get resource for contact exports
IContactExportCollectionResource contactExportsResource = contactsResource.Exports();

// Prepare filters for contacts export
var filters = new List<ContactExportFilterBase>
{
    new ContactExportListIdFilter(new List<int> { 123, 456 }),
    new ContactExportSubscriptionStatusFilter(ContactExportFilterSubscriptionStatus.Subscribed)
};

// Create contact export request
var exportRequest = new CreateContactExportRequest(filters);

// Create contact export
ContactExport exportResponse = await contactExportsResource.Create(exportRequest);
Console.WriteLine($"Created contact export with ID: {exportResponse.Id}");

// Get resource for specific contact export
IContactExportResource contactExportResource = contactsResource.Export(exportResponse.Id);

// Get details of specific contact export
ContactExport exportDetails = await contactExportResource.GetDetails();
Console.WriteLine($"Export status: {exportDetails.Status}");
Console.WriteLine($"Created at: {exportDetails.CreatedAt}");

if (exportDetails.Status == ContactExportStatus.Finished && exportDetails.Url != null)
{
    Console.WriteLine("File ready for download");
    Console.WriteLine($"Export URL: {exportDetails.Url}");
}
```

### Track Contact Events

Create custom events for contacts to track user actions, behaviors, and engagement.

```csharp
using Mailtrap.ContactEvents;
using Mailtrap.ContactEvents.Models;
using Mailtrap.ContactEvents.Requests;

long accountId = 12345;
long contactId = 67890;

IAccountResource accountResource = mailtrapClient.Account(accountId);
IContactCollectionResource contactsResource = accountResource.Contacts();

// Get resource for contact events collection
IContactEventCollectionResource contactEventsResource = contactsResource.Events(contactId);

// Create contact event with custom parameters
var createEventRequest = new CreateContactEventRequest("product_purchased");
createEventRequest.Params.Add("product_id", 101);
createEventRequest.Params.Add("product_name", "Premium Subscription");
createEventRequest.Params.Add("amount", 99.99);
createEventRequest.Params.Add("currency", "USD");
createEventRequest.Params.Add("is_recurring", true);

ContactEvent contactEvent = await contactEventsResource.Create(createEventRequest);
Console.WriteLine($"Contact event created: {contactEvent.Name}");
Console.WriteLine($"Contact ID: {contactEvent.ContactId}");
Console.WriteLine($"Contact email: {contactEvent.ContactEmail}");

foreach (KeyValuePair<string, object?> param in contactEvent.Params)
{
    Console.WriteLine($"Parameter: {param.Key} = {param.Value}");
}
```

### Manage Email Templates

Create, retrieve, update, and delete email templates for reusable email designs.

```csharp
using Mailtrap.EmailTemplates;
using Mailtrap.EmailTemplates.Models;
using Mailtrap.EmailTemplates.Requests;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);

// Get resource for email templates collection
IEmailTemplateCollectionResource emailTemplatesResource = accountResource.EmailTemplates();

// Get all email templates
IList<EmailTemplate> emailTemplates = await emailTemplatesResource.GetAll();

// Create a new email template
var createRequest = new CreateEmailTemplateRequest(
    name: "Welcome Email",
    category: "Onboarding",
    subject: "Welcome to {{company_name}}!")
{
    BodyHtml = "<h1>Welcome {{user_name}}!</h1><p>We're excited to have you on board.</p>",
    BodyText = "Welcome {{user_name}}! We're excited to have you on board."
};
EmailTemplate newTemplate = await emailTemplatesResource.Create(createRequest);
Console.WriteLine($"Created template: {newTemplate.Name} with ID: {newTemplate.Id}");

// Get specific template details
IEmailTemplateResource emailTemplateResource = accountResource.EmailTemplate(newTemplate.Id);
EmailTemplate templateDetails = await emailTemplateResource.GetDetails();

// Update email template
var updateRequest = new UpdateEmailTemplateRequest(
    name: "Updated Welcome Email",
    category: "User Onboarding",
    subject: "Welcome aboard, {{user_name}}!")
{
    BodyHtml = "<h1>Hello {{user_name}}!</h1><p>Welcome to {{company_name}}. Let's get started!</p>",
    BodyText = "Hello {{user_name}}! Welcome to {{company_name}}. Let's get started!"
};
EmailTemplate updatedTemplate = await emailTemplateResource.Update(updateRequest);
Console.WriteLine($"Updated template: {updatedTemplate.Name}");

// Delete email template
await emailTemplateResource.Delete();
Console.WriteLine("Email template deleted successfully");
```

### Manage Suppressions

Manage email suppression lists to handle unsubscribes, bounces, and complaints.

```csharp
using Mailtrap.Suppressions;
using Mailtrap.Suppressions.Models;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);

// Get resource for suppressions collection
ISuppressionCollectionResource suppressionsResource = accountResource.Suppressions();

// Fetch suppressions with filter
var suppressionFilter = new SuppressionFilter
{
    Email = "test@example.com"
};
IList<Suppression> suppressions = await suppressionsResource.Fetch(suppressionFilter);

if (suppressions.Count > 0)
{
    Suppression suppression = suppressions.First();
    Console.WriteLine($"Found suppression for: {suppression.Email}");
    Console.WriteLine($"Reason: {suppression.Reason}");
}

// Fetch all suppressions (without filter)
IList<Suppression> allSuppressions = await suppressionsResource.Fetch();
Console.WriteLine($"Total suppressions: {allSuppressions.Count}");

// Get resource for specific suppression
if (suppressions.Count > 0)
{
    ISuppressionResource suppressionResource = accountResource.Suppression(suppressions.First().Id);

    // Delete the suppression (re-enable email sending)
    Suppression? deletedSuppression = await suppressionResource.Delete();
    Console.WriteLine($"Deleted suppression for: {deletedSuppression?.Email}");
}
```

### Get Account Information

Retrieve information about accounts you have access to including account details and permissions.

```csharp
using Mailtrap.Accounts;
using Mailtrap.Accounts.Models;

// Get all accounts
IAccountCollectionResource accountsResource = mailtrapClient.Accounts();
IList<Account> accounts = await accountsResource.GetAll();

foreach (Account account in accounts)
{
    Console.WriteLine($"Account: {account.Name}");
    Console.WriteLine($"  ID: {account.Id}");
    Console.WriteLine($"  Access Level: {account.AccessLevels}");
}

// Get specific account details
long accountId = accounts.First().Id;
IAccountResource accountResource = mailtrapClient.Account(accountId);
Account accountDetails = await accountResource.GetDetails();
Console.WriteLine($"Account {accountDetails.Name} has {accountDetails.AccessLevels} access");
```

### Check Billing and Usage Statistics

Retrieve current billing cycle usage statistics for testing and sending email services.

```csharp
using Mailtrap.Billing;
using Mailtrap.Billing.Models;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);
IBillingResource billingResource = accountResource.Billing();

BillingUsage billingUsage = await billingResource.GetUsage();

Console.WriteLine($"Billing Period: {billingUsage.Period.StartDate} to {billingUsage.Period.EndDate}");

// Testing usage
if (billingUsage.Testing != null)
{
    Console.WriteLine("\nEmail Testing:");
    Console.WriteLine($"  Plan: {billingUsage.Testing.Plan.Name}");
    Console.WriteLine($"  Emails Used: {billingUsage.Testing.Statistics.Emails.Used} / {billingUsage.Testing.Statistics.Emails.Total}");
    Console.WriteLine($"  Inboxes Used: {billingUsage.Testing.Statistics.Inboxes.Used} / {billingUsage.Testing.Statistics.Inboxes.Total}");
}

// Sending usage
if (billingUsage.Sending != null)
{
    Console.WriteLine("\nEmail Sending:");
    Console.WriteLine($"  Plan: {billingUsage.Sending.Plan.Name}");
    Console.WriteLine($"  Emails Used: {billingUsage.Sending.Statistics.Emails.Used} / {billingUsage.Sending.Statistics.Emails.Total}");
}
```

### Manage Account Access and Permissions

Grant, update, and revoke access permissions for users on specific resources within an account.

```csharp
using Mailtrap.AccountAccesses;
using Mailtrap.AccountAccesses.Models;
using Mailtrap.AccountAccesses.Requests;
using Mailtrap.AccountAccesses.Responses;

long accountId = 12345;
IAccountResource accountResource = mailtrapClient.Account(accountId);

// Get all account accesses
IAccountAccessCollectionResource accessesResource = accountResource.AccountAccesses();
IList<AccountAccess> accesses = await accessesResource.GetAll();

foreach (AccountAccess access in accesses)
{
    Console.WriteLine($"User: {access.Resources.First().Access.Name}");
}

// Update permissions for specific user access
long accessId = accesses.First().Id;
IAccountAccessResource accessResource = accountResource.AccountAccess(accessId);

var updateRequest = new UpdatePermissionsRequest
{
    Resources = new List<UpdatePermissionsRequestItem>
    {
        new UpdatePermissionsRequestItem
        {
            ResourceType = ResourceType.Project,
            ResourceId = 54321,
            AccessLevel = AccessLevel.Admin
        }
    }
};

UpdatePermissionsResponse updateResponse = await accessResource.UpdatePermissions(updateRequest);
Console.WriteLine($"Permissions updated successfully: {updateResponse.Success}");

// Delete account access (revoke access)
DeleteAccountAccessResponse deleteResponse = await accessResource.Delete();
Console.WriteLine($"Access revoked: {deleteResponse.Success}");
```

### Configure Client with Dependency Injection

Set up the Mailtrap client in ASP.NET Core applications using built-in dependency injection and configuration.

```csharp
using Mailtrap;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

// Option 1: Configure from appsettings.json
IConfigurationSection config = builder.Configuration.GetSection("Mailtrap");
builder.Services.AddMailtrapClient(config);

// Option 2: Configure inline
builder.Services.AddMailtrapClient(options =>
{
    options.ApiToken = "your-api-token-here";
    options.DefaultEmailClient = "transactional"; // or "bulk" or "test"
    options.DefaultInboxId = 12345; // required if using "test" as default
});

// appsettings.json structure:
// {
//   "Mailtrap": {
//     "ApiToken": "your-api-token-here",
//     "DefaultEmailClient": "transactional",
//     "DefaultInboxId": 12345
//   }
// }

IHost app = builder.Build();

// Inject and use the client
var mailtrapClient = app.Services.GetRequiredService<IMailtrapClient>();
```

### Use Client Factory Pattern (Without DI)

Create Mailtrap client instances directly using the factory pattern when dependency injection is not available.

```csharp
using Mailtrap;
using Mailtrap.Configuration;

// Create client using factory
var options = new MailtrapClientOptions
{
    ApiToken = "your-api-token-here"
};

IMailtrapClient mailtrapClient = MailtrapClientFactory.Create(options);

// Use the client
SendEmailRequest request = SendEmailRequest
    .Create()
    .From("sender@example.com")
    .To("recipient@example.com")
    .Subject("Test Email")
    .Text("This is a test email.");

SendEmailResponse response = await mailtrapClient.Email().Send(request);
Console.WriteLine($"Email sent: {response.Success}");
```

### Error Handling

Handle Mailtrap-specific exceptions and API errors with detailed error information and proper exception types.

```csharp
using Mailtrap.Core.Exceptions;

try
{
    SendEmailRequest request = SendEmailRequest
        .Create()
        .From("sender@example.com")
        .To("recipient@example.com")
        .Subject("Test")
        .Text("Content");

    SendEmailResponse response = await mailtrapClient.Email().Send(request);
}
catch (RequestValidationException validationEx)
{
    // Request validation failed before sending
    Console.WriteLine("Validation errors:");
    foreach (var error in validationEx.ValidationResult.Errors)
    {
        Console.WriteLine($"  {error.PropertyName}: {error.ErrorMessage}");
    }
}
catch (MailtrapApiException apiEx)
{
    // API returned an error response
    Console.WriteLine($"API Error: {apiEx.Message}");
    Console.WriteLine($"Status Code: {apiEx.StatusCode}");
    if (apiEx.Problem != null)
    {
        Console.WriteLine($"Title: {apiEx.Problem.Title}");
        Console.WriteLine($"Detail: {apiEx.Problem.Detail}");
    }
}
catch (HttpRequestFailedException httpEx)
{
    // HTTP request failed (network issues, timeouts, etc.)
    Console.WriteLine($"HTTP Error: {httpEx.Message}");
    Console.WriteLine($"Status Code: {httpEx.StatusCode}");
}
catch (MailtrapException mtEx)
{
    // Base exception for all Mailtrap-related errors
    Console.WriteLine($"Mailtrap Error: {mtEx.Message}");
}
catch (OperationCanceledException)
{
    // Request was cancelled
    Console.WriteLine("Request was cancelled");
}
```

## Summary

The Mailtrap .NET Client provides a comprehensive solution for email management in .NET applications, covering both development/testing scenarios and production email delivery. The primary use cases include sending transactional emails (password resets, order confirmations, notifications), managing bulk email campaigns (newsletters, marketing emails), testing email functionality in a sandbox environment before production deployment, managing contacts and mailing lists with custom fields and segmentation, tracking contact events and engagement, importing and exporting contacts in bulk, managing email templates for reusable designs, and managing email infrastructure through programmatic access to inboxes, projects, domain configurations, and suppression lists. The library's fluent API design makes it easy to construct complex email requests, while the built-in validation ensures data integrity before making API calls.

Integration patterns typically involve registering the Mailtrap client in the dependency injection container during application startup, then injecting `IMailtrapClient` into services that need to send emails or manage email infrastructure. The client supports both configuration-based setup through appsettings.json and programmatic configuration for flexible deployment scenarios. For testing, developers can use the sandbox functionality to send emails to testing inboxes, inspect message content, analyze spam scores, and verify HTML rendering without delivering to real recipients. The contacts management features enable sophisticated email marketing campaigns with custom segmentation, field management, bulk operations, and event tracking for user behavior analysis. The SDK's exception handling model provides clear differentiation between validation errors, API errors, and network failures, enabling robust error recovery strategies in production applications.