Persiltech.Membership.Email 0.3.0

dotnet add package Persiltech.Membership.Email --version 0.3.0
                    
NuGet\Install-Package Persiltech.Membership.Email -Version 0.3.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Persiltech.Membership.Email" Version="0.3.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Persiltech.Membership.Email" Version="0.3.0" />
                    
Directory.Packages.props
<PackageReference Include="Persiltech.Membership.Email" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Persiltech.Membership.Email --version 0.3.0
                    
#r "nuget: Persiltech.Membership.Email, 0.3.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Persiltech.Membership.Email@0.3.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Persiltech.Membership.Email&version=0.3.0
                    
Install as a Cake Addin
#tool nuget:?package=Persiltech.Membership.Email&version=0.3.0
                    
Install as a Cake Tool

Persiltech.Membership.Email

NuGet License: MIT Sponsor

Adaptador de correo de Persiltech.Membership: compone los avisos de confirmación de correo, reinicio de contraseña y cambio de correo a partir de plantillas HTML, y los entrega por Persiltech.Email.

Persiltech.Membership deja IMembershipEmailSender sin implementar a propósito, porque redactar el mensaje exige conocer la marca, el diseño y las rutas de la aplicación. Este paquete pone esas tres cosas en Options y en plantillas sustituibles, de modo que dos aplicaciones distintas comparten el mismo binario.

Instalación

dotnet add package Persiltech.Membership.Email

Uso

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSmtpEmailSender(options => builder.Configuration.GetSection("Smtp").Bind(options));
builder.Services.AddMembershipEmail(options => builder.Configuration.GetSection("MembershipEmail").Bind(options));

AddMembershipEmail no registra el transporte: IEmailSender lo aporta el consumidor, normalmente con AddSmtpEmailSender de Persiltech.Email, porque elegir servidor y credenciales es suyo. El orden entre ambas llamadas da igual; lo que no puede es faltar una.

Con la configuración correspondiente:

{
  "MembershipEmail": {
    "BrandName": "Persiltech",
    "ClientBaseUrl": "https://app.example.com",
    "LogoUrl": "https://cdn.example.com/logo.png",
    "PrimaryColor": "#0d6efd",
    "SupportEmail": "soporte@example.com"
  }
}

Las opciones se validan al arrancar la aplicación, no en el primer aviso: el registro usa un IValidateOptions<MembershipEmailOptions> y encadena ValidateOnStart(). Los fallos salen todos juntos, no de uno en uno.

Dos de las reglas evitan fallos silenciosos que de otro modo nadie ve: TemplatesDirectory tiene que existir —apuntando a un directorio que no está, se servirían las plantillas embebidas y el rebrandeo no se aplicaría sin avisar— y LogoUrl tiene que ser absoluta, porque los clientes de correo no resuelven rutas relativas. El validador se registra con TryAddSingleton: uno propio registrado antes gana.

El contrato

public sealed class MembershipEmailOptions
{
    public string BrandName { get; set; } = string.Empty;      // obligatorio
    public string ClientBaseUrl { get; set; } = string.Empty;  // obligatoria, http o https absoluta

    public string EmailConfirmationPath { get; set; } = "/confirm-email";
    public string PasswordResetPath { get; set; } = "/reset-password";
    public string EmailChangePath { get; set; } = "/confirm-email-change";

    public string? LogoUrl { get; set; }                       // si se indica, absoluta
    public string PrimaryColor { get; set; } = "#0d6efd";      // #rgb o #rrggbb
    public string OnPrimaryColor { get; set; } = "#ffffff";    // el texto que va encima
    public string Language { get; set; } = "es";               // etiqueta BCP 47
    public string? SupportEmail { get; set; }

    public string? TemplatesDirectory { get; set; }            // si se indica, tiene que existir
}

OnPrimaryColor es el color del rótulo del encabezado y del texto del botón. Existe porque el blanco no siempre vale: sobre una marca clara —un amarillo, un verde lima— el botón deja de leerse, y el paquete no puede elegirlo sin conocer la marca.

Language va al atributo lang del documento. No traduce nada —el texto vive en las plantillas— pero sin él una aplicación que las traduzca seguiría anunciando español, y un lector de pantalla lo pronunciaría así.

ClientBaseUrl es la raíz de la aplicación cliente —la que abre el usuario—, no la de la API, y de ella cuelgan las tres rutas.

Los enlaces

Cada aviso lleva un enlace de vuelta con los datos que la pantalla tiene que devolver a la API. Los nombres de los parámetros salen de los contratos de Persiltech.Membership, que identifican la cuenta por el correo:

Aviso Enlace
Confirmación de correo {ClientBaseUrl}{EmailConfirmationPath}?email=…&token=…
Reinicio de contraseña {ClientBaseUrl}{PasswordResetPath}?email=…&token=…
Cambio de correo {ClientBaseUrl}{EmailChangePath}?newEmail=…&token=…

Ambos valores viajan codificados con Uri.EscapeDataString: los testigos de ASP.NET Core Identity traen + y /, y sin codificar se pierden por el camino.

Las plantillas

Cada aviso son tres archivos embebidos en el ensamblado, bajo Templates/:

Aviso Nombre Archivos
Confirmación de correo EmailConfirmation .subject.txt, .html, .txt
Reinicio de contraseña PasswordReset .subject.txt, .html, .txt
Cambio de correo EmailChange .subject.txt, .html, .txt
Bloqueo de la cuenta AccountLocked .subject.txt, .html, .txt

El .html de cada aviso es solo el interior: el encabezado, el ancho de 600 píxeles y el pie viven una vez en Layout.html, que envuelve a los cuatro. El .txt es la parte alternativa en texto plano, que un correo transaccional no debería omitir.

AccountLocked es el único sin enlace de vuelta. No lleva testigo —con uno, fallar la contraseña de alguien bastaría para mandarle un enlace de reinicio que no ha pedido—, así que no hay pantalla a la que dirigir a nadie y el marcador {{ActionUrl}} no aparece en su plantilla. A cambio dispone de {{LockoutMinutes}}, los minutos que dura el bloqueo. Se manda la duración y no la hora a la que termina para no tener que acertar con la zona horaria de quien lo lee.

Cambiar el diseño

TemplatesDirectory apunta a una carpeta cuyos archivos ganan a los embebidos, por nombre. Basta con dejar ahí el que se quiera cambiar —Layout.html para rebrandear entero, o el .html de un aviso suelto—; el resto siguen saliendo del paquete. Las plantillas se leen una vez y se cachean, así que un cambio en disco exige reiniciar la aplicación.

Para la mayoría de los casos no hace falta llegar ahí: el logotipo, los dos colores, el idioma y el correo de contacto son configuración. Sustituir plantillas es para cambiar el texto —traducirlo, por ejemplo— o la maqueta.

Qué hay detrás del diseño

Un correo no es una página web: se abre en decenas de clientes que interpretan el HTML de forma distinta, y varios llevan veinte años sin cambiar. Estas plantillas dan por sentado eso, y conviene saberlo antes de tocarlas:

  • El botón va por duplicado. Outlook de escritorio usa el motor de Word, que no entiende border-radius ni el relleno de un inline-block: sin la variante VML de dentro del condicional <!--[if mso]>, el botón le sale como texto suelto. El resto de clientes ven el enlace normal.
  • Modo oscuro. Se declaran ambos esquemas y la maqueta trae su paleta oscura. Sin eso, Apple Mail y Outlook.com invierten el fondo por su cuenta y dejan el texto oscuro sobre fondo oscuro.
  • Todo el estilo va en línea. Gmail descarta el <style> en varios contextos; el bloque solo lleva lo que mejora la experiencia y cuya ausencia no rompe nada —las medias consultas—.
  • En móvil el botón ocupa el ancho y mide 48 px de alto, por encima del mínimo táctil recomendado, y el cuerpo va a 16 px.
  • Cada aviso trae su versión en texto plano. No es un adorno: hay clientes y filtros que la prefieren, y un transaccional sin ella puntúa peor en entrega.
  • Ninguna imagen es imprescindible. Muchos clientes las bloquean por defecto, así que el mensaje se entiende entero sin cargar ninguna; el logotipo es opcional y lleva alt.

Si sustituyes Layout.html o el .html de un aviso, estas propiedades se pierden salvo que las mantengas. Lo más fácil es partir del archivo del paquete y editarlo.

Marcadores

La sintaxis es {{Nombre}}. Un marcador que no corresponda a ningún valor lanza InvalidOperationException nombrándolo: una plantilla con un nombre mal tecleado tiene que fallar en el primer envío de prueba, no llegar en blanco al buzón de un cliente.

Marcador Origen
FirstName, LastName, FullName El aviso.
Email Destinatario del aviso.
ActionUrl Enlace de vuelta, ya construido.
LockoutMinutes Solo en AccountLocked: minutos que dura el bloqueo.
BrandName, PrimaryColor, OnPrimaryColor, Language, SupportEmail Las opciones.
BrandHeader El logotipo como <img> si hay LogoUrl; si no, la marca en texto.
SupportLine El contacto del pie ya maquetado, o nada si no hay SupportEmail.
SupportLineText Lo mismo para la versión en texto plano.
Year Año en curso, para el pie.
Preheader El asunto ya sustituido.
Body Solo en Layout.html: el interior del aviso.

SupportLine y SupportLineText existen porque SupportEmail es opcional y el compositor no tiene condicionales: escribiendo el separador y el mailto: directamente en la plantilla, un despliegue sin correo de contacto acababa con un · colgando y un enlace vacío.

En el .html los valores se insertan codificados —solo lo sensible en HTML: los acentos viajan tal cual—; en el .txt y en el asunto, crudos. Body y BrandHeader son las dos excepciones: son marcado que genera el propio paquete.

Otro motor de plantillas

IEmailTemplateRenderer es público y se registra con TryAddSingleton, así que una implementación propia —con Scriban, Fluid o lo que sea— registrada antes de AddMembershipEmail gana:

public interface IEmailTemplateRenderer
{
    RenderedEmail Render(string templateName, IReadOnlyDictionary<string, string?> values);
}

public sealed record RenderedEmail(string Subject, string HtmlBody, string TextBody);

Decisiones de diseño

  • Plantillas en archivos, no en cadenas de C#. El HTML de correo es tabular y con estilos en línea: en archivos se previsualiza en un navegador, lo puede tocar un diseñador y el encabezado y el pie se escriben una sola vez.
  • Ni Razor ni un motor de terceros de partida. Razor exige ASP.NET Core y compilación en tiempo de ejecución para tres correos transaccionales. IEmailTemplateRenderer es la costura por la que entra un motor con condicionales el día que haga falta.
  • La marca y las rutas son configuración. Es lo que separa a este paquete de un adaptador escrito dentro de una aplicación.
  • Un marcador desconocido lanza. Es determinista, así que salta en la primera prueba de quien escribe la plantilla.
  • El paquete no elige el transporte. Depende de IEmailSender, no de SMTP.

Compatibilidad

net10.0. Requiere Persiltech.Membership y Persiltech.Email.

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.3.0 Nueva plantilla AccountLocked, para el aviso de bloqueo de cuenta que estrena Persiltech.Membership 0.9.0. Es la única sin enlace de vuelta: no lleva testigo, así que no hay pantalla a la que dirigir a nadie. Dispone de {{LockoutMinutes}} y dice cuánto dura el bloqueo en lugar de a qué hora termina, para no depender de la zona horaria de quien lo lee.<br><br>Rediseño de las cuatro plantillas. El botón gana su variante VML para Outlook de escritorio, donde salía como texto suelto. Los mensajes dejan de quedar ilegibles en modo oscuro. En móvil el botón ocupa el ancho y mide 48 px de alto, y el cuerpo sube a 16 px. Se corrige el pie cuando no hay SupportEmail: escribía un separador colgando y un mailto: vacío. Dos opciones nuevas, OnPrimaryColor —el blanco no se lee sobre una marca clara— y Language —el idioma estaba fijado a español dentro de la maqueta—, y cuatro marcadores nuevos para quien sustituya plantillas.
0.2.0 ClientBaseUrls: una dirección de vuelta por portal, elegida con la cabecera clientId que envía el frontal. Con una sola dirección, quien pedía su contraseña desde el portal de clientes recibía un enlace hacia el administrativo. La clave solo elige entre lo configurado; una desconocida cae en ClientBaseUrl.
0.1.0 Primera versión: implementa IMembershipEmailSender con plantillas HTML embebidas y sustituibles, la marca y las rutas del cliente como configuración, y la entrega por IEmailSender.

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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.3.0 132 9/16/2026
0.2.0 126 9/13/2026
0.1.0 136 9/6/2026

v0.3.0
     - Nueva plantilla AccountLocked, para el aviso de bloqueo de cuenta que estrena Persiltech.Membership 0.9.0
     - Es el unico aviso sin enlace de vuelta: no lleva testigo, asi que no hay pantalla a la que mandar a nadie
     - Dice cuantos minutos dura el bloqueo, en lugar de a que hora termina, para no depender de la zona horaria de quien lee
     - Como los demas, se puede sustituir por archivo con MembershipEmailOptions.TemplatesDirectory

     - Rediseno de las cuatro plantillas. El boton gana su version VML para Outlook de escritorio, que usa el motor de Word y lo dejaba como texto suelto
     - Modo oscuro: los mensajes ya no quedan con texto oscuro sobre fondo oscuro en Apple Mail ni en Outlook.com
     - En movil el boton ocupa el ancho y mide 48 px de alto, por encima del minimo tactil; el cuerpo sube a 16 px
     - Se corrige el pie cuando SupportEmail no esta configurado: antes escribia un separador colgando y un enlace mailto: vacio
     - Nueva opcion OnPrimaryColor: el blanco sobre una marca clara no se lee, y el paquete no puede elegirlo sin conocerla
     - Nueva opcion Language: el idioma del documento estaba fijado a espanol dentro de la maqueta
     - Nuevos marcadores para quien sustituya las plantillas: OnPrimaryColor, Language, SupportLine y SupportLineText

     v0.1.0
     - Primera versión: implementa IMembershipEmailSender de Persiltech.Membership con plantillas HTML
     - La marca, los colores y las rutas del cliente son configuración, no código
     - Las plantillas embebidas se sustituyen por archivo con MembershipEmailOptions.TemplatesDirectory
     - Las opciones se validan al arrancar con IValidateOptions, acumulando todos los fallos