Adfines.Net.Zumbi - Envío de Correos Electrónicos para .NET

📋 Descripción

Adfines.Net.Zumbi es un paquete NuGet diseñado para simplificar y optimizar el envío de correos electrónicos en aplicaciones .NET 5+. Ofrece funcionalidades avanzadas para el envío individual y masivo de correos, con soporte para envío paralelo, cifrado de credenciales, logging de errores y manejo de adjuntos.

🚀 Características Principales

• ✅ Envío individual y masivo de correos electrónicos
• 🔄 Envío paralelo con control de concurrencia
• 🔒 Cifrado automático de contraseñas
• 📝 Sistema de logging integrado de errores
• 📎 Soporte para adjuntos (attachments)
• ⚡ Configuración flexible desde código o appsettings.json
• 📊 HTML y texto plano en el cuerpo de correos
• 🔧 Múltiples protocolos SSL/TLS

📦 Instalación

dotnet add package Adfines.Net.Zumbi

🔐 Encriptación de Contraseñas

using Adfines.Net.Zumbi;

// Para encriptar contraseñas (cuando encrypt = true)
string passwordEncriptado = Password.E("Hola mundo");
Console.WriteLine(passwordEncriptado);
// El valor retornado es el que se debe colocar en Password cuando encrypt es true

🔧 CONFIGURACIÓN

Configuración desde Código

var zum = new ZumMail(
    x: "smtp.office365.com",           // URL del servidor SMTP
    port: 587,                         // Puerto del servidor
    email: "correo@ejemplo.com",       // Email remitente
    password: "SbBW2UXX83XHhG9Wr/tVQ4sGZ2B7S9zBAJvtOMfkM/k=", // Contraseña (encriptada)
    ssl: true,                         // Habilitar SSL (opcional, default: false)
    tls: true,                         // Habilitar TLS (opcional, default: false)
    html: true,                        // Cuerpo en HTML (opcional, default: false)
    log: true,                         // Habilitar logging (opcional, default: false)
    dateTimeTitle: true,               // Agregar fecha/hora al título (opcional, default: false)
    encrypt: true                      // Contraseña encriptada (opcional, default: false)
);

Configuración desde appsettings.json

var zum = new ZumMail("ejemplo");

appsettings.json:

{
  "AdfinesZumbiNet": {
    "ejemplo": {
      "Url": "smtp.office365.com",
      "Port": 587,
      "Email": "correo@ejemplo.com",
      "Password": "SbBW2UXX83XHhG9Wr/tVQ4sGZ2B7S9zBAJvtOMfkM/k=",
      "Ssl": true,
      "Tls": true,
      "Html": true,
      "Log": true,
      "DateTimeTitle": true,
      "Encrypt": true
    }
  }
}

💻 USO DEL PAQUETE

Envío Individual de Correo

// Generar UUID para tracking
var messageCode = Guid.NewGuid().ToString();

// Enviar correo individual
zum.SendMail(
    mask: "Nombre Remitente",                      // Nombre que aparece como remitente
    mailTo: ["destinatario1@ejemplo.com", "destinatario2@ejemplo.com"], // Lista de destinatarios
    mailCo: ["copiaoculta@ejemplo.com"],          // Copias ocultas (CC)
    title: "Asunto del Correo",                   // Asunto del correo
    body: "<h1>Contenido del Correo</h1>",        // Cuerpo del correo (HTML o texto)
    attachment: null,                             // Ruta a archivo adjunto (opcional)
    uuid: messageCode                             // ID único para tracking
);

Preparación de Correos para Envío Masivo

Forma 1: Instancia con Propiedades

var mail = new ZumMailList()
{
    Uuid = Guid.NewGuid().ToString(),
    Mask = "Nombre Remitente",
    Title = "Asunto del Correo",
    Body = "<h1>Contenido del Correo</h1>",
};
mail.MailTo.Add("destinatario1@ejemplo.com");
mail.MailTo.Add("destinatario2@ejemplo.com");
mail.MailCo.Add("copiaoculta@ejemplo.com");

Forma 2: Constructor con Parámetros

var mail2 = new ZumMailList(
    to: ["destinatario1@ejemplo.com", "destinatario2@ejemplo.com"],  // Destinatarios
    co: ["copiaoculta@ejemplo.com"],                               // Copias ocultas
    attachment: null                                                // Adjunto
)
{
    Uuid = Guid.NewGuid().ToString(),
    Mask = "Nombre Remitente",
    Title = "Asunto del Correo",
    Body = "<h1>Contenido del Correo</h1>",
};

Creación de Lista de Correos

var mails = new List<ZumMailList>()
{
    mail,
    mail2,
    new ZumMailList(
        to: ["destinatario3@ejemplo.com", "destinatario4@ejemplo.com"],
        co: ["copiaoculta2@ejemplo.com"],
        attachment: null
    )
    {
        Uuid = Guid.NewGuid().ToString(),
        Mask = "Nombre Remitente",
        Title = "Asunto del Correo",
        Body = "<h1>Contenido del Correo</h1>",
    }
};

Envío Masivo con Paralelismo Controlado

// Enviar correos en paralelo
// Segundo parámetro: grado de paralelismo
// 2 = envía de 2 en 2 correos
// 0 = envía todos los correos simultáneamente
zum.SendMail(mails, 2);

🐛 MANEJO DE ERRORES Y LOGGING

Acceso a Errores

// Revisar todos los errores ocurridos
foreach (var error in zum.Errs)
{
    Console.WriteLine($@"
        Hubo un problema: 
        Codigo Unico: {error.Uuid}
        Razon: {error.Reason}
        Mensaje: {error.Message}
        Excepcion (error): {error.Exception}
    ");
}

Limpieza de Logs

// Limpiar el historial de errores
zum.Errs.Clear();

📊 ESTRUCTURAS DE DATOS

ZumMailList - Constructor

ZumMailList - Propiedades

Error Structure (zum.Errs)

🔍 EJEMPLOS COMPLETOS

Ejemplo 1: Sistema de Notificaciones Masivas

var zum = new ZumMail(
    x: "smtp.gmail.com",
    port: 587,
    email: "notificaciones@empresa.com",
    password: Password.E("MiContraseñaSegura"),
    ssl: true,
    tls: true,
    html: true,
    log: true,
    encrypt: true
);

// Preparar notificaciones para todos los usuarios
var notificaciones = new List<ZumMailList>();

foreach (var usuario in listaUsuarios)
{
    notificaciones.Add(new ZumMailList(
        to: [usuario.Email],
        co: null,
        attachment: null
    )
    {
        Uuid = Guid.NewGuid().ToString(),
        Mask = "Sistema de Notificaciones",
        Title = $"Nueva actualización - {DateTime.Now:dd/MM/yyyy}",
        Body = $@"
            <h1>Hola {usuario.Nombre}</h1>
            <p>Tenemos nuevas actualizaciones disponibles.</p>
            <p>Visita nuestro portal para más información.</p>
        "
    });
}

// Enviar notificaciones en paralelo (5 a la vez)
zum.SendMail(notificaciones, 5);

// Revisar errores
if (zum.Errs.Any())
{
    Console.WriteLine($"Errores: {zum.Errs.Count}");
    foreach (var error in zum.Errs)
    {
        // Registrar en sistema de logging
        Log.Error($"Error enviando correo {error.Uuid}: {error.Message}");
    }
    
    // Limpiar después de procesar
    zum.Errs.Clear();
}

Ejemplo 2: Correo con Adjunto

var messageCode = Guid.NewGuid().ToString();
var rutaAdjunto = @"C:\Documentos\Reporte.pdf";

zum.SendMail(
    mask: "Departamento de Finanzas",
    mailTo: ["contabilidad@empresa.com"],
    mailCo: ["gerencia@empresa.com"],
    title: "Reporte Mensual",
    body: @"
        <h2>Reporte Financiero</h2>
        <p>Adjunto encontrarás el reporte del mes.</p>
        <p>Saludos,<br/>Finanzas</p>
    ",
    attachment: rutaAdjunto,
    uuid: messageCode
);

Ejemplo 3: Newsletter Semanal

var newsletter = new List<ZumMailList>();

// Agregar múltiples suscriptores
foreach (var suscriptor in suscriptores)
{
    newsletter.Add(new ZumMailList(
        to: [suscriptor.Email],
        co: ["marketing@empresa.com"],
        attachment: @"C:\Newsletters\semanal.pdf"
    )
    {
        Uuid = Guid.NewGuid().ToString(),
        Mask = "Equipo de Marketing",
        Title = $"Newsletter Semanal - {DateTime.Now:MMMM yyyy}",
        Body = $@"
            <h1>¡Hola {suscriptor.Nombre}!</h1>
            <p>Aquí tienes nuestro newsletter semanal con las últimas novedades.</p>
            <p>No dudes en contactarnos si tienes preguntas.</p>
        "
    });
}

// Enviar newsletter a todos los suscriptores
zum.SendMail(newsletter, 10); // 10 correos en paralelo

❓ PREGUNTAS FRECUENTES (FAQ)

¿Cómo elijo el grado de paralelismo?

• 0: Todos los correos se envían simultáneamente (máxima concurrencia)
• 1: Correos enviados uno por uno (secuencial)
• n: Correos enviados en grupos de n correos
• Recomendado: Para servidores SMTP estándar, usar entre 5-10 para evitar bloqueos

¿Qué servidores SMTP son compatibles?

Cualquier servidor SMTP estándar:

• Office 365: smtp.office365.com
• Gmail: smtp.gmail.com
• Outlook: smtp-mail.outlook.com
• Servidores corporativos personalizados

¿Cómo manejo contraseñas encriptadas?

1. Use Password.E("su-contraseña") para obtener la versión encriptada
2. Establezca encrypt: true en la configuración
3. Use la contraseña encriptada en el parámetro password

¿Puedo deshabilitar el logging?

Sí, establezca log: false en la configuración. Esto evitará que se acumulen errores en zum.Errs.

¿Qué sucede con los correos que fallan en envío masivo?

• Los correos que fallan se registran automáticamente en zum.Errs
• El sistema continúa con los siguientes correos
• Puede revisar zum.Errs después del envío para procesar los fallos

¿Cómo manejo adjuntos grandes?

• Asegúrese de que el archivo existe y es accesible
• Verifique los límites de tamaño del servidor SMTP
• Considere comprimir archivos grandes antes de adjuntarlos

📝 NOTAS IMPORTANTES

Configuración de Servidor

• Siempre use UUIDs únicos para cada correo para tracking efectivo
• Configure adecuadamente SSL/TLS según los requisitos de su proveedor de correo
• Para Office 365/Gmail, normalmente necesita ssl: true y tls: true

Envíos Masivos

• Para envíos masivos, ajuste el paralelismo según los límites de su servidor SMTP
• Los servidores gratuitos (Gmail, Outlook) tienen límites estrictos de envío por día
• Considere implementar delays entre lotes grandes de correos

Seguridad

• Nunca almacene contraseñas en texto plano
• Siempre use encrypt: true en entornos de producción
• Revise periódicamente zum.Errs para detectar problemas de autenticación

Mantenimiento

• Realice limpieza periódica con zum.Errs.Clear() para evitar acumulación de memoria
• Monitoree los tiempos de envío para ajustar el paralelismo óptimo
• Implemente mecanismos de reintento para correos fallidos

Consideraciones Técnicas

• Los adjuntos deben estar accesibles desde el servidor donde se ejecuta la aplicación
• El cuerpo HTML debe ser válido para una correcta visualización
• Para templates complejos, considere usar sistemas de plantillas externos