How to Build a Simple Email Conversion Web API in ASP.NET Core

Creating a microservice or Web API for email conversion enables other applications to leverage conversion functionality without integrating the entire Aspose.Email library. This approach provides a centralized, scalable solution that can serve multiple clients, applications, or systems. Using ASP.NET Core and the Aspose.Email LowCode Converter, you can build a robust RESTful service that accepts email files via HTTP uploads and returns converted files for download.

Why Build an Email Conversion API?

A dedicated email conversion API offers several advantages:

Centralized Processing: Single service handles all conversion logic
Cross-Platform Access: Any application can consume the API via HTTP
Scalability: Deploy independently and scale based on demand
Technology Independence: Clients don’t need .NET or Aspose.Email dependencies
Microservice Architecture: Fits modern distributed application patterns
Resource Management: Centralized control over processing resources

Prerequisites

Before building the email conversion API, ensure you have:

ASP.NET Core 6.0 or higher development environment
Visual Studio 2022 or Visual Studio Code with C# extensions
Aspose.Email NuGet package
Basic knowledge of RESTful API design
Understanding of file upload/download in web APIs

Step 1: Set Up the API Project

Create a new ASP.NET Core Web API project:

dotnet new webapi -n EmailConverterApi
cd EmailConverterApi
dotnet add package Aspose.Email
dotnet add package Swashbuckle.AspNetCore

Configure the project file (EmailConverterApi.csproj):

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspose.Email" Version="24.3.0" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
  </ItemGroup>

</Project>

Step 2: Create the Email Converter Controller

Create a comprehensive controller that handles email conversion operations:

using Aspose.Email.LowCode;
using Microsoft.AspNetCore.Mvc;
using System.ComponentModel.DataAnnotations;

namespace EmailConverterApi.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    [Produces("application/json")]
    public class EmailConverterController : ControllerBase
    {
        private readonly ILogger<EmailConverterController> _logger;
        private readonly IConfiguration _configuration;
        private readonly long _maxFileSize;
        private readonly string[] _allowedExtensions = { ".eml", ".msg" };
        private readonly string[] _supportedOutputFormats = { "html", "eml", "msg", "mhtml", "mht" };

        public EmailConverterController(ILogger<EmailConverterController> logger, IConfiguration configuration)
        {
            _logger = logger;
            _configuration = configuration;
            _maxFileSize = _configuration.GetValue<long>("MaxFileSize", 10 * 1024 * 1024); // 10MB default
        }

        /// <summary>
        /// Converts an email file to the specified format
        /// </summary>
        /// <param name="emailFile">The email file to convert (EML or MSG)</param>
        /// <param name="format">Output format (html, eml, msg, mhtml, mht)</param>
        /// <param name="filename">Optional custom filename for the output</param>
        /// <returns>The converted file for download</returns>
        [HttpPost("convert")]
        [ProducesResponseType(typeof(FileResult), 200)]
        [ProducesResponseType(typeof(ApiErrorResponse), 400)]
        [ProducesResponseType(typeof(ApiErrorResponse), 500)]
        public async Task<IActionResult> ConvertEmail(
            [Required] IFormFile emailFile,
            [FromQuery, Required] string format = "html",
            [FromQuery] string? filename = null)
        {
            var requestId = Guid.NewGuid().ToString("N")[..8];
            _logger.LogInformation("Starting conversion request {RequestId} for file: {FileName}, format: {Format}", 
                requestId, emailFile?.FileName, format);

            try
            {
                // Validate request
                var validationResult = ValidateRequest(emailFile, format);
                if (validationResult != null)
                {
                    _logger.LogWarning("Validation failed for request {RequestId}: {Error}", requestId, validationResult.Message);
                    return validationResult;
                }

                // Create in-memory output handler
                var outputHandler = new MemoryOutputHandler();
                
                // Perform conversion
                using var inputStream = emailFile!.OpenReadStream();
                await ConvertEmailInternal(inputStream, emailFile.FileName, outputHandler, format);

                // Get converted content
                var convertedContent = outputHandler.GetContent();
                var outputFileName = filename ?? GenerateOutputFileName(emailFile.FileName, format);
                var contentType = GetContentType(format);

                _logger.LogInformation("Successfully converted {RequestId}: {InputFile} -> {OutputFile} ({Size} bytes)", 
                    requestId, emailFile.FileName, outputFileName, convertedContent.Length);

                // Return file for download
                return File(convertedContent, contentType, outputFileName);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Conversion failed for request {RequestId}: {Error}", requestId, ex.Message);
                return StatusCode(500, new ApiErrorResponse 
                { 
                    Message = "Internal server error during conversion", 
                    RequestId = requestId 
                });
            }
        }

        /// <summary>
        /// Gets information about supported formats and API capabilities
        /// </summary>
        [HttpGet("info")]
        [ProducesResponseType(typeof(ApiInfoResponse), 200)]
        public IActionResult GetApiInfo()
        {
            return Ok(new ApiInfoResponse
            {
                SupportedInputFormats = _allowedExtensions,
                SupportedOutputFormats = _supportedOutputFormats,
                MaxFileSizeMB = _maxFileSize / (1024 * 1024),
                Version = "1.0.0",
                Description = "Email format conversion API powered by Aspose.Email"
            });
        }

        /// <summary>
        /// Health check endpoint
        /// </summary>
        [HttpGet("health")]
        [ProducesResponseType(typeof(HealthResponse), 200)]
        public IActionResult HealthCheck()
        {
            return Ok(new HealthResponse 
            { 
                Status = "Healthy", 
                Timestamp = DateTime.UtcNow,
                Version = "1.0.0"
            });
        }

        private IActionResult? ValidateRequest(IFormFile? emailFile, string format)
        {
            if (emailFile == null || emailFile.Length == 0)
            {
                return BadRequest(new ApiErrorResponse { Message = "No file provided or file is empty" });
            }

            if (emailFile.Length > _maxFileSize)
            {
                return BadRequest(new ApiErrorResponse 
                { 
                    Message = $"File size exceeds maximum allowed size of {_maxFileSize / (1024 * 1024)}MB" 
                });
            }

            var extension = Path.GetExtension(emailFile.FileName)?.ToLowerInvariant();
            if (string.IsNullOrEmpty(extension) || !_allowedExtensions.Contains(extension))
            {
                return BadRequest(new ApiErrorResponse 
                { 
                    Message = $"Unsupported file format. Allowed formats: {string.Join(", ", _allowedExtensions)}" 
                });
            }

            if (string.IsNullOrEmpty(format) || !_supportedOutputFormats.Contains(format.ToLowerInvariant()))
            {
                return BadRequest(new ApiErrorResponse 
                { 
                    Message = $"Unsupported output format. Supported formats: {string.Join(", ", _supportedOutputFormats)}" 
                });
            }

            return null;
        }

        private static async Task ConvertEmailInternal(Stream inputStream, string fileName, IOutputHandler outputHandler, string format)
        {
            switch (format.ToLowerInvariant())
            {
                case "html":
                    await Converter.ConvertToHtml(inputStream, fileName, outputHandler);
                    break;
                case "eml":
                    await Converter.ConvertToEml(inputStream, fileName, outputHandler);
                    break;
                case "msg":
                    await Converter.ConvertToMsg(inputStream, fileName, outputHandler);
                    break;
                case "mhtml":
                    await Converter.ConvertToMhtml(inputStream, fileName, outputHandler);
                    break;
                case "mht":
                    await Converter.ConvertToMht(inputStream, fileName, outputHandler);
                    break;
                default:
                    throw new ArgumentException($"Unsupported conversion format: {format}");
            }
        }

        private static string GenerateOutputFileName(string inputFileName, string format)
        {
            var nameWithoutExtension = Path.GetFileNameWithoutExtension(inputFileName);
            return $"{nameWithoutExtension}.{format.ToLowerInvariant()}";
        }

        private static string GetContentType(string format) => format.ToLowerInvariant() switch
        {
            "html" => "text/html",
            "eml" => "message/rfc822",
            "msg" => "application/vnd.ms-outlook",
            "mhtml" => "message/rfc822",
            "mht" => "message/rfc822",
            _ => "application/octet-stream"
        };
    }
}

Step 3: Create the In-Memory Output Handler

Create a custom output handler that captures converted content in memory:

using Aspose.Email.LowCode;
using System.Text;

namespace EmailConverterApi.Services
{
    /// <summary>
    /// Output handler that captures converted content in memory for API responses
    /// </summary>
    public class MemoryOutputHandler : IOutputHandler
    {
        private byte[]? _content;
        private string? _fileName;

        public async Task AddOutputStream(string name, Func<Stream, Task> writeAction)
        {
            _fileName = name;
            using var memoryStream = new MemoryStream();
            await writeAction(memoryStream);
            _content = memoryStream.ToArray();
        }

        public void AddOutputStream(string name, Action<Stream> writeAction)
        {
            _fileName = name;
            using var memoryStream = new MemoryStream();
            writeAction(memoryStream);
            _content = memoryStream.ToArray();
        }

        public byte[] GetContent()
        {
            return _content ?? throw new InvalidOperationException("No content has been written to this handler");
        }

        public string GetContentAsString()
        {
            var content = GetContent();
            return Encoding.UTF8.GetString(content);
        }

        public string GetFileName()
        {
            return _fileName ?? throw new InvalidOperationException("No file name available");
        }

        public bool HasContent => _content != null && _content.Length > 0;
    }
}

Step 4: Create Response Models

Define structured response models for the API:

namespace EmailConverterApi.Models
{
    /// <summary>
    /// Standard error response model
    /// </summary>
    public class ApiErrorResponse
    {
        public string Message { get; set; } = string.Empty;
        public string? RequestId { get; set; }
        public DateTime Timestamp { get; set; } = DateTime.UtcNow;
        public string? Details { get; set; }
    }

    /// <summary>
    /// API information response model
    /// </summary>
    public class ApiInfoResponse
    {
        public string[] SupportedInputFormats { get; set; } = Array.Empty<string>();
        public string[] SupportedOutputFormats { get; set; } = Array.Empty<string>();
        public long MaxFileSizeMB { get; set; }
        public string Version { get; set; } = string.Empty;
        public string Description { get; set; } = string.Empty;
    }

    /// <summary>
    /// Health check response model
    /// </summary>
    public class HealthResponse
    {
        public string Status { get; set; } = string.Empty;
        public DateTime Timestamp { get; set; }
        public string Version { get; set; } = string.Empty;
        public Dictionary<string, object>? AdditionalInfo { get; set; }
    }

    /// <summary>
    /// Conversion request model for batch operations
    /// </summary>
    public class BatchConversionRequest
    {
        public string OutputFormat { get; set; } = "html";
        public bool ZipOutput { get; set; } = true;
        public string? CustomPrefix { get; set; }
    }

    /// <summary>
    /// Batch conversion result
    /// </summary>
    public class BatchConversionResult
    {
        public int TotalFiles { get; set; }
        public int SuccessfulConversions { get; set; }
        public int FailedConversions { get; set; }
        public List<ConversionError> Errors { get; set; } = new();
        public string? OutputFileName { get; set; }
    }

    /// <summary>
    /// Individual conversion error details
    /// </summary>
    public class ConversionError
    {
        public string FileName { get; set; } = string.Empty;
        public string ErrorMessage { get; set; } = string.Empty;
    }
}

Step 5: Add Batch Conversion Support

Extend the controller to support batch conversions:

/// <summary>
/// Converts multiple email files and returns them as a ZIP archive
/// </summary>
/// <param name="emailFiles">Multiple email files to convert</param>
/// <param name="request">Batch conversion settings</param>
/// <returns>ZIP file containing all converted emails</returns>
[HttpPost("convert-batch")]
[ProducesResponseType(typeof(FileResult), 200)]
[ProducesResponseType(typeof(ApiErrorResponse), 400)]
[ProducesResponseType(typeof(ApiErrorResponse), 500)]
public async Task<IActionResult> ConvertEmailBatch(
    [Required] IFormFileCollection emailFiles,
    [FromForm] BatchConversionRequest request)
{
    var requestId = Guid.NewGuid().ToString("N")[..8];
    _logger.LogInformation("Starting batch conversion request {RequestId} for {FileCount} files, format: {Format}", 
        requestId, emailFiles.Count, request.OutputFormat);

    try
    {
        if (!emailFiles.Any())
        {
            return BadRequest(new ApiErrorResponse { Message = "No files provided for batch conversion" });
        }

        if (!_supportedOutputFormats.Contains(request.OutputFormat.ToLowerInvariant()))
        {
            return BadRequest(new ApiErrorResponse 
            { 
                Message = $"Unsupported output format: {request.OutputFormat}" 
            });
        }

        var results = new List<(string FileName, byte[] Content, bool Success, string? Error)>();

        // Process each file
        foreach (var file in emailFiles)
        {
            try
            {
                var validationResult = ValidateRequest(file, request.OutputFormat);
                if (validationResult != null)
                {
                    results.Add((file.FileName, Array.Empty<byte>(), false, "Validation failed"));
                    continue;
                }

                var outputHandler = new MemoryOutputHandler();
                using var inputStream = file.OpenReadStream();
                
                await ConvertEmailInternal(inputStream, file.FileName, outputHandler, request.OutputFormat);
                
                results.Add((file.FileName, outputHandler.GetContent(), true, null));
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to convert file {FileName} in batch {RequestId}", file.FileName, requestId);
                results.Add((file.FileName, Array.Empty<byte>(), false, ex.Message));
            }
        }

        // Create ZIP archive
        var zipContent = CreateZipArchive(results, request);
        var zipFileName = $"converted_emails_{DateTime.Now:yyyyMMdd_HHmmss}.zip";

        _logger.LogInformation("Batch conversion {RequestId} completed: {Success}/{Total} successful", 
            requestId, results.Count(r => r.Success), results.Count);

        return File(zipContent, "application/zip", zipFileName);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Batch conversion failed for request {RequestId}: {Error}", requestId, ex.Message);
        return StatusCode(500, new ApiErrorResponse 
        { 
            Message = "Internal server error during batch conversion", 
            RequestId = requestId 
        });
    }
}

private static byte[] CreateZipArchive(List<(string FileName, byte[] Content, bool Success, string? Error)> results, BatchConversionRequest request)
{
    using var zipStream = new MemoryStream();
    using (var archive = new System.IO.Compression.ZipArchive(zipStream, System.IO.Compression.ZipArchiveMode.Create, true))
    {
        // Add successful conversions
        foreach (var (fileName, content, success, _) in results.Where(r => r.Success))
        {
            var outputFileName = GenerateOutputFileName(fileName, request.OutputFormat);
            if (!string.IsNullOrEmpty(request.CustomPrefix))
            {
                outputFileName = $"{request.CustomPrefix}_{outputFileName}";
            }

            var entry = archive.CreateEntry(outputFileName);
            using var entryStream = entry.Open();
            entryStream.Write(content, 0, content.Length);
        }

        // Add error log if there were failures
        var failures = results.Where(r => !r.Success).ToList();
        if (failures.Any())
        {
            var errorLog = string.Join("\n", failures.Select(f => $"{f.FileName}: {f.Error}"));
            var errorEntry = archive.CreateEntry("conversion_errors.txt");
            using var errorStream = errorEntry.Open();
            using var writer = new StreamWriter(errorStream);
            writer.Write(errorLog);
        }
    }

    return zipStream.ToArray();
}

Step 6: Configure the Application

Set up the application with proper configuration in Program.cs:

using EmailConverterApi.Services;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Add services
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Email Converter API",
        Version = "v1",
        Description = "RESTful API for converting email files between different formats using Aspose.Email",
        Contact = new OpenApiContact
        {
            Name = "API Support",
            Email = "support@example.com"
        }
    });
    
    // Include XML comments if available
    var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    if (File.Exists(xmlPath))
    {
        c.IncludeXmlComments(xmlPath);
    }
});

// Configure file upload limits
builder.Services.Configure<IISServerOptions>(options =>
{
    options.MaxRequestBodySize = 50 * 1024 * 1024; // 50MB
});

// Add CORS if needed
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAll", policy =>
    {
        policy.AllowAnyOrigin()
              .AllowAnyHeader()
              .AllowAnyMethod();
    });
});

// Add logging
builder.Logging.AddConsole();
builder.Logging.AddDebug();

var app = builder.Build();

// Configure pipeline
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Email Converter API V1");
        c.RoutePrefix = string.Empty; // Swagger at root
    });
}

app.UseHttpsRedirection();
app.UseCors("AllowAll");
app.UseAuthorization();
app.MapControllers();

app.Run();

Step 7: Configuration Settings

Add configuration in appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "EmailConverterApi": "Debug"
    }
  },
  "AllowedHosts": "*",
  "MaxFileSize": 52428800,
  "ConversionSettings": {
    "DefaultOutputFormat": "html",
    "EnableBatchConversion": true,
    "MaxBatchSize": 10,
    "TempDirectory": "temp"
  }
}

Step 8: Add Error Handling Middleware

Create global error handling middleware:

using System.Net;
using System.Text.Json;

namespace EmailConverterApi.Middleware
{
    public class GlobalErrorHandlingMiddleware
    {
        private readonly RequestDelegate _next;
        private readonly ILogger<GlobalErrorHandlingMiddleware> _logger;

        public GlobalErrorHandlingMiddleware(RequestDelegate next, ILogger<GlobalErrorHandlingMiddleware> logger)
        {
            _next = next;
            _logger = logger;
        }

        public async Task InvokeAsync(HttpContext context)
        {
            try
            {
                await _next(context);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "An unhandled exception occurred");
                await HandleExceptionAsync(context, ex);
            }
        }

        private static async Task HandleExceptionAsync(HttpContext context, Exception exception)
        {
            context.Response.ContentType = "application/json";
            
            var (statusCode, message) = exception switch
            {
                ArgumentException => (HttpStatusCode.BadRequest, exception.Message),
                FileNotFoundException => (HttpStatusCode.NotFound, "Requested file not found"),
                UnauthorizedAccessException => (HttpStatusCode.Unauthorized, "Access denied"),
                NotSupportedException => (HttpStatusCode.BadRequest, "Operation not supported"),
                _ => (HttpStatusCode.InternalServerError, "An error occurred while processing your request")
            };

            context.Response.StatusCode = (int)statusCode;

            var response = new
            {
                message = message,
                statusCode = (int)statusCode,
                timestamp = DateTime.UtcNow
            };

            await context.Response.WriteAsync(JsonSerializer.Serialize(response));
        }
    }
}

// Register middleware in Program.cs
app.UseMiddleware<GlobalErrorHandlingMiddleware>();

Step 9: Client Usage Examples

cURL Examples

Convert a single file:

curl -X POST "https://localhost:5001/api/emailconverter/convert?format=html" \
  -H "Content-Type: multipart/form-data" \
  -F "emailFile=@sample.eml" \
  -o converted.html

Get API information:

curl -X GET "https://localhost:5001/api/emailconverter/info"

C# Client Example

public class EmailConverterClient
{
    private readonly HttpClient _httpClient;
    
    public EmailConverterClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }
    
    public async Task<byte[]> ConvertEmailAsync(string filePath, string outputFormat = "html")
    {
        using var form = new MultipartFormDataContent();
        using var fileStream = File.OpenRead(filePath);
        using var fileContent = new StreamContent(fileStream);
        
        fileContent.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/octet-stream");
        form.Add(fileContent, "emailFile", Path.GetFileName(filePath));
        
        var response = await _httpClient.PostAsync($"/api/emailconverter/convert?format={outputFormat}", form);
        response.EnsureSuccessStatusCode();
        
        return await response.Content.ReadAsByteArrayAsync();
    }
}

JavaScript Client Example

async function convertEmail(file, format = 'html') {
    const formData = new FormData();
    formData.append('emailFile', file);
    
    const response = await fetch(`/api/emailconverter/convert?format=${format}`, {
        method: 'POST',
        body: formData
    });
    
    if (!response.ok) {
        throw new Error(`Conversion failed: ${response.statusText}`);
    }
    
    return await response.blob();
}

Conclusion

Building an email conversion Web API with ASP.NET Core and Aspose.Email LowCode Converter creates a powerful, reusable service that provides:

Centralized Processing: Single service handles all email conversions
Cross-Platform Access: HTTP-based interface works with any client technology
Scalability: Deploy and scale independently of client applications
Comprehensive Features: Support for multiple formats, batch processing, and error handling
Production Ready: Includes logging, configuration, validation, and documentation

This API architecture enables organizations to provide email conversion capabilities as a service, supporting multiple applications and use cases while maintaining centralized control over processing logic and resources. The microservice approach facilitates modern application architectures and enables easy integration with existing systems and workflows.