Persiltech.Email
0.1.1
dotnet add package Persiltech.Email --version 0.1.1
NuGet\Install-Package Persiltech.Email -Version 0.1.1
<PackageReference Include="Persiltech.Email" Version="0.1.1" />
<PackageVersion Include="Persiltech.Email" Version="0.1.1" />
<PackageReference Include="Persiltech.Email" />
paket add Persiltech.Email --version 0.1.1
#r "nuget: Persiltech.Email, 0.1.1"
#:package Persiltech.Email@0.1.1
#addin nuget:?package=Persiltech.Email&version=0.1.1
#tool nuget:?package=Persiltech.Email&version=0.1.1
Persiltech.Email
Envío de correo electrónico por SMTP en .NET: el contrato IEmailSender y su implementación
con MailKit, con configuración por Options y registro en la inyección de dependencias.
El paquete transporta, no redacta. Recibe un asunto y un cuerpo ya compuestos y los entrega al servidor. Quién elige plantilla, formato, idioma y enlaces es la aplicación consumidora, que es la única que conoce sus propias rutas.
Instalación
dotnet add package Persiltech.Email
El contrato
public interface IEmailSender
{
Task SendAsync(EmailMessage message, CancellationToken cancellationToken);
}
public sealed record EmailMessage
{
public required string To { get; init; }
public required string Subject { get; init; }
public required string HtmlBody { get; init; }
public string? TextBody { get; init; }
}
SendAsync completa cuando el servidor SMTP acepta el mensaje. Eso no es la entrega al
buzón del destinatario: lo que ocurra después del salto está fuera del alcance de SMTP.
To admite la dirección sola (juan@example.com) o acompañada del nombre visible
(Juan Pérez <juan@example.com>), y se analiza al enviar. TextBody es el cuerpo
alternativo en texto plano: si es null, el mensaje viaja solo con la parte HTML.
El remitente no viaja en el mensaje, sino en las opciones, porque es propiedad de la cuenta SMTP con la que se conecta y no de cada envío:
public sealed class SmtpOptions
{
public string Host { get; set; } = string.Empty; // obligatorio
public int Port { get; set; } = 587; // 1 – 65535
public SmtpSecurity Security { get; set; } = SmtpSecurity.Auto;
public string? UserName { get; set; }
public string? Password { get; set; } // obligatoria si hay UserName
public string FromAddress { get; set; } = string.Empty; // obligatoria
public string? FromDisplayName { get; set; }
public int TimeoutInSeconds { get; set; } = 30; // 1 – 600
}
public enum SmtpSecurity
{
Auto = 0,
None = 1,
StartTls = 2,
SslOnConnect = 3
}
UserName y Password son opcionales porque un relay local de desarrollo (Papercut,
MailHog) no autentica: si UserName viene vacío, no se llama a Authenticate.
SmtpSecurity decide el cifrado de la conexión: Auto lo deduce del puerto y de lo que
anuncie el servidor, StartTls es lo habitual en el 587, SslOnConnect en el 465, y None
solo tiene sentido contra un relay local.
Uso
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSmtpEmailSender(options => builder.Configuration.GetSection("Smtp").Bind(options));
var app = builder.Build();
app.MapPost("/email", async (
SendEmailRequest request,
IEmailSender emailSender,
CancellationToken cancellationToken) =>
{
var message = new EmailMessage
{
To = request.To,
Subject = request.Subject,
HtmlBody = request.HtmlBody,
TextBody = request.TextBody
};
await emailSender.SendAsync(message, cancellationToken);
return Results.NoContent();
});
app.Run();
Con la configuración correspondiente:
{
"Smtp": {
"Host": "smtp.example.com",
"Port": 587,
"Security": "StartTls",
"UserName": "no-reply@example.com",
"Password": "...",
"FromAddress": "no-reply@example.com",
"FromDisplayName": "Persiltech"
}
}
AddSmtpEmailSender valida las opciones al arrancar la aplicación, no en el primer
envío: registra un IValidateOptions<SmtpOptions> y encadena ValidateOnStart(), de modo
que un host vacío detiene el arranque en lugar de perder el primer correo que alguien
esperaba recibir. Los fallos salen todos juntos, no de uno en uno.
Las reglas son: Host y FromAddress obligatorios, Port entre 1 y 65535,
TimeoutInSeconds entre 1 y 600, y Password obligatoria cuando se configura UserName.
FromAddress se comprueba con el mismo analizador que la compondrá al enviar, así que lo
que pase aquí pasa también en tiempo de ejecución.
El validador se registra con TryAddSingleton: si prefieres tus propias reglas, registra un
IValidateOptions<SmtpOptions> antes de llamar a AddSmtpEmailSender y el tuyo gana.
De dónde salgan los valores es del consumidor: el delegado admite tanto el enlace de la configuración como literales. La contraseña es un secreto y el paquete no la registra en ningún log.
Errores
Un destinatario que no se puede analizar sale como ArgumentException con
ParamName = "To", antes de conectar con nadie: se comprueba con el mismo criterio con
el que se valida FromAddress al arrancar, así que una dirección sin dominio no llega a
salir por el cable para que la rechace el servidor en el RCPT TO.
Lo demás no se envuelve: un servidor inalcanzable o unas credenciales rechazadas salen tal cual, como excepciones de MailKit o de sockets. Si tu aplicación quiere una categoría propia de error, la envuelve ella, que es quien sabe qué hacer con cada caso.
Tampoco reintenta: el envío es un intento, síncrono respecto de quien llama.
Decisiones de diseño
- El paquete transporta, no redacta. Recibe el asunto y el cuerpo ya compuestos. Redactar aquí obligaría a elegir plantilla, formato e idioma, y a inventarse las rutas de una aplicación que no es la suya.
SmtpSecurityes un tipo propio, y no el de MailKit. Así el arranque del consumidor no necesita conocer la biblioteca de transporte, que es un detalle de implementación y no aparece en la superficie pública.- La implementación no se expone. El consumidor resuelve
IEmailSender; publicar el nombre de la clase convertiría en contrato algo que no lo es. - Una conexión por envío. El cliente SMTP de MailKit no es seguro para uso concurrente, así que cada envío abre la suya, envía y la cierra. Un pool compartido es una optimización que este paquete no ha demostrado necesitar.
- Sin dependencia de ASP.NET Core. Sirve igual a una API web, a un worker o a una aplicación de consola.
Quedan fuera, de momento: varios destinatarios, copia y copia oculta, adjuntos, plantillas, reintentos y colas, y cualquier transporte que no sea SMTP.
Compatibilidad
net10.0.
Estado
Versión 0.x: la superficie pública puede cambiar entre versiones menores.
Historial de versiones
El código fuente vive en el monorepo; esta tabla resume qué cambió en cada versión publicada.
| Versión | Cambios |
|---|---|
| 0.1.1 | El .nuspec declara el repositorio, ahora público, y se activa SourceLink: el depurador del consumidor puede entrar al código fuente. El README enlaza al monorepo y el soporte pasa a las incidencias de GitHub. Sin cambios en el código ni en la superficie pública. |
| 0.1.0 | Primera versión: el contrato IEmailSender, el EmailMessage y la implementación SMTP con MailKit, con las opciones validadas al arrancar. |
Soporte
Para dudas, fallos o peticiones abre una incidencia. También puedes consultar la página del paquete.
Apoyar el desarrollo
Si el paquete te ahorra trabajo, puedes apoyar su mantenimiento en GitHub Sponsors.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- MailKit (>= 4.17.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.11)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.11)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Persiltech.Email:
| Package | Downloads |
|---|---|
|
Persiltech.Membership.Email
Adaptador de correo de Persiltech.Membership: compone los avisos de confirmación, reinicio de contraseña y cambio de correo a partir de plantillas HTML y los entrega por Persiltech.Email. |
GitHub repositories
This package is not used by any popular GitHub repositories.
v0.1.1
- El .nuspec declara el repositorio, ahora público, y activa SourceLink: el depurador del consumidor puede entrar al código fuente
- El README enlaza al monorepo y el soporte pasa a las incidencias de GitHub
- Sin cambios en el código ni en la superficie pública
v0.1.0
- Primera versión: el contrato IEmailSender y su implementación SMTP con MailKit
- Las opciones se validan al arrancar con IValidateOptions, acumulando todos los fallos
- Remitente y destinatario se analizan con el mismo criterio, que rechaza direcciones sin dominio