Hymma.NeverBounce

⚠️ DISCLAIMER: This is NOT an official NeverBounce package. This is a community-maintained .NET client library created by HYMMA. For official SDKs and support, please visit NeverBounce.

A modern .NET 8 client library for the NeverBounce email validation API. Validate email addresses before sending to reduce bounces and protect your sender reputation.

Features

• Single Email Validation - Validate individual email addresses in real-time
• Comprehensive Results - Get detailed validation status, flags, and typo suggestions
• Dependency Injection - Easy integration with ASP.NET Core and .NET Generic Host
• Configurable - Customize timeouts, error handling, and more
• Well Tested - Comprehensive unit test coverage
• Modern .NET - Built for .NET 8 with nullable reference types

Installation

From NuGet.org

dotnet add package Hymma.NeverBounce

From Local Build

dotnet pack -c Release
dotnet add package Hymma.NeverBounce --source ./src/Hymma.NeverBounce/bin/Release

Quick Start

1. Register Services

// In Program.cs or Startup.cs

// Option 1: With API key directly
builder.Services.AddNeverBounce("secret_your_api_key_here");

// Option 2: From configuration
builder.Services.AddNeverBounce(builder.Configuration);

// Option 3: With custom options
builder.Services.AddNeverBounce(options =>
{
    options.ApiKey = "secret_your_api_key_here";
    options.TimeoutSeconds = 30;
    options.ThrowOnError = false;
});

2. Add Configuration (if using Option 2)

// appsettings.json
{
  "NeverBounce": {
    "ApiKey": "secret_your_api_key_here",
    "TimeoutSeconds": 30
  }
}

3. Use the Client

public class EmailService
{
    private readonly INeverBounceClient _neverBounce;

    public EmailService(INeverBounceClient neverBounce)
    {
        _neverBounce = neverBounce;
    }

    public async Task SendEmailAsync(string email, string message)
    {
        // Validate before sending
        var result = await _neverBounce.ValidateAsync(email);

        if (!result.IsSafeToSend)
        {
            throw new InvalidOperationException(
                $"Cannot send to {email}: {result.Status}");
        }

        // Check for typo suggestions
        if (!string.IsNullOrEmpty(result.SuggestedCorrection))
        {
            // Maybe prompt user: "Did you mean {result.SuggestedCorrection}?"
        }

        // Proceed with sending...
    }
}

Validation Statuses

Status	IsSafeToSend	Description
Valid	✅ Yes	Verified real address that can receive emails
Invalid	❌ No	Verified as not valid - will hard bounce
Disposable	❌ No	Temporary/disposable address - high bounce risk
Catchall	✅ Yes	Domain accepts all emails (unverifiable)
Unknown	❌ No	Server cannot be reached - status unknown
Error	❌ No	Validation service error or timeout

Result Properties

var result = await client.ValidateAsync("test@example.com");

// Core properties
result.Email              // The email that was validated
result.Status             // EmailValidationStatus enum
result.IsSafeToSend       // true for Valid or Catchall

// Flags
result.IsDisposable       // Temporary email service
result.IsRoleAccount      // info@, support@, etc.
result.IsFreeEmail        // Gmail, Yahoo, etc.
result.HasBadSyntax       // Invalid email format
result.HasDns             // Domain has DNS records
result.HasMxRecords       // Domain has MX records
result.Flags              // Raw list of all flags

// Additional info
result.SuggestedCorrection // Typo fix suggestion
result.ExecutionTimeMs     // API response time
result.RawResponse         // Raw JSON (if enabled)

Configuration Options

services.AddNeverBounce(options =>
{
    // Required: Your NeverBounce API key
    options.ApiKey = "secret_xxx";

    // API base URL (default: production API)
    options.BaseUrl = "https://api.neverbounce.com/v4.2";

    // Request timeout in seconds (default: 30)
    options.TimeoutSeconds = 30;

    // Throw exception on API errors instead of returning Error status
    options.ThrowOnError = false;

    // Include raw JSON response in results for debugging
    options.IncludeRawResponse = false;
});

Account Information

Check your credit balance:

var info = await client.GetAccountInfoAsync();

Console.WriteLine($"Free credits remaining: {info.FreeCreditsRemaining}");
Console.WriteLine($"Paid credits remaining: {info.PaidCreditsRemaining}");

Error Handling

Default Behavior (ThrowOnError = false)

var result = await client.ValidateAsync(email);

if (result.Status == EmailValidationStatus.Error)
{
    // API error occurred - handle gracefully
    // You might want to allow the email through or retry
}

Strict Mode (ThrowOnError = true)

try
{
    var result = await client.ValidateAsync(email);
}
catch (NeverBounceException ex)
{
    Console.WriteLine($"API Error: {ex.Message}");
    Console.WriteLine($"Status Code: {ex.StatusCode}");
}

Best Practices

1. Validate at entry point - Validate emails when users enter them, not just before sending
2. Handle catchall carefully - These emails may or may not exist
3. Log suggestions - Track typo corrections for UX improvements
4. Monitor credits - Set up alerts when credits run low
5. Cache results - Consider caching validation results to reduce API calls

API Reference

• NeverBounce API Documentation
• Single Check Endpoint

License

MIT License - see LICENSE file for details.