ForwardEmail.Net 1.0.0

ForwardEmail.Net

A .NET client library for the Forward Email API.

Installation

dotnet add package ForwardEmail.Net

Getting Started

You'll need a Forward Email API key from your account security settings.

Basic setup

using ForwardEmail.Net;

var client = new ForwardEmailClient(new ForwardEmailClientOptions
{
    ApiKey = "your-api-key"
});

ASP.NET Core / Dependency Injection

Register the client with the DI container (recommended for web applications):

// Program.cs
builder.Services.AddForwardEmailClient("your-api-key");

// Or use the options overload for custom configuration
builder.Services.AddForwardEmailClient(options =>
{
    options.ApiKey = "your-api-key";
    options.BaseUrl = "https://api.forwardemail.net"; // default
});

Then inject it into your services:

public class MyService(ForwardEmailClient client)
{
    // use client
}

Using an existing HttpClient

// Useful in test scenarios or when you manage HttpClient lifetime yourself
var httpClient = new HttpClient();
var client = new ForwardEmailClient(httpClient, new ForwardEmailClientOptions
{
    ApiKey = "your-api-key"
});

Usage Examples

Account

// Get current account
var account = await client.GetAccountAsync();
Console.WriteLine($"Email: {account?.Email}, Plan: {account?.Plan}");

// Update account profile
var updated = await client.UpdateAccountAsync(new UpdateAccountRequest
{
    GivenName = "Jane",
    FamilyName = "Doe"
});

Domains

// List all domains
var domains = await client.ListDomainsAsync();

// Create a domain
var domain = await client.CreateDomainAsync(new CreateDomainRequest
{
    Domain = "example.com",
    HasPhishingProtection = true,
    HasVirusProtection = true
});

// Get a specific domain
var domain = await client.GetDomainAsync("example.com");

// Verify DNS records
var verified = await client.VerifyDomainRecordsAsync("example.com");

// Delete a domain
bool deleted = await client.DeleteDomainAsync("example.com");

Aliases

// List aliases for a domain
var aliases = await client.ListAliasesAsync("example.com");

// Create an alias
var alias = await client.CreateAliasAsync("example.com", new CreateAliasRequest
{
    Name = "hello",
    Recipients = new List<string> { "you@gmail.com" },
    Description = "Main contact alias",
    HasImap = true
});

// Get a specific alias by ID
var alias = await client.GetAliasAsync("example.com", aliasId);

// Update an alias (e.g., enable vacation responder)
var updated = await client.UpdateAliasAsync("example.com", aliasId, new UpdateAliasRequest
{
    VacationResponderIsEnabled = true,
    VacationResponderSubject = "Out of office",
    VacationResponderMessage = "I'll be back on Monday."
});

// Disable an alias
await client.UpdateAliasAsync("example.com", aliasId, new UpdateAliasRequest
{
    IsEnabled = false
});

// Generate a password for IMAP/SMTP access
var result = await client.GenerateAliasPasswordAsync("example.com", aliasId,
    new GenerateAliasPasswordRequest
    {
        NewPassword = "s3cr3tPassword!",
        EmailedInstructions = "you@gmail.com"
    });

// Delete an alias
bool deleted = await client.DeleteAliasAsync("example.com", aliasId);

Outbound Emails

// Check sending limit
var limit = await client.GetEmailLimitAsync();
Console.WriteLine($"Remaining: {limit?.Count}");

// Send an email
var email = await client.CreateEmailAsync(new CreateEmailRequest
{
    From = "hello@example.com",
    To = "recipient@example.com",
    Subject = "Hello from ForwardEmail.Net",
    Text = "Plain text body.",
    Html = "<p>HTML body.</p>"
});
Console.WriteLine($"Email ID: {email?.Id}");

// List sent emails
var emails = await client.ListEmailsAsync(page: 1, limit: 25);

// Get a specific email
var email = await client.GetEmailAsync(emailId);

// Delete an email
bool deleted = await client.DeleteEmailAsync(emailId);

Catch-All Passwords

// List catch-all passwords for a domain
var passwords = await client.ListCatchAllPasswordsAsync("example.com");

// Create a catch-all password
var password = await client.CreateCatchAllPasswordAsync("example.com",
    new CreateCatchAllPasswordRequest
    {
        NewPassword = "s3cr3tPassword!",
        Description = "Shared inbox password"
    });

// Delete a catch-all password by token ID
bool deleted = await client.DeleteCatchAllPasswordAsync("example.com", tokenId);

Domain Members & Invites

// Invite a user to a domain
await client.CreateInviteAsync("example.com", new CreateInviteRequest
{
    Email = "colleague@example.com",
    Group = "user" // or "admin"
});

// Remove an invite
await client.RemoveInviteAsync("example.com", "colleague@example.com");

// Update a member's role
await client.UpdateMemberAsync("example.com", memberId, "admin");

// Remove a member
await client.RemoveMemberAsync("example.com", memberId);

Logs

// Download logs as raw bytes (save to file or process in memory)
byte[]? logs = await client.DownloadLogsAsync(domain: "example.com");
if (logs != null)
    await File.WriteAllBytesAsync("logs.csv", logs);

// Filter logs by search query or bounce category
byte[]? bounceLogs = await client.DownloadLogsAsync(
    domain: "example.com",
    bounceCategory: "hard"
);

Encrypt a TXT Record

This endpoint does not require authentication.

string? encrypted = await client.EncryptAsync("forward-email=you@gmail.com");
Console.WriteLine(encrypted); // use this value in your DNS TXT record

Error Handling

API errors throw a ForwardEmailException containing the HTTP status code and error message:

try
{
    var domain = await client.GetDomainAsync("nonexistent.com");
}
catch (ForwardEmailException ex)
{
    Console.WriteLine($"Status: {(int)ex.StatusCode} – {ex.ErrorMessage}");
}

Cancellation

All async methods accept an optional CancellationToken:

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
var account = await client.GetAccountAsync(cts.Token);

Target Frameworks

• .NET Framework 4.6.2
• .NET Standard 2.0 (includes ASP.NET Core DI extension)

License

MIT