Skip to content

Mail

In Puerto a mail is a domain concept with a port, like a repository. The code that decides to send it depends on EnviadorCorreoBienvenida, never on SMTP, and its text lives in three template files you edit like any other file.

puerto generar correo bienvenida -- nombre:String plan:opt:String
output
✓ Mail 'bienvenida' added — yours from here on:
contextos/correo/dominio/src/bienvenida.rs CorreoBienvenida + the port EnviadorCorreoBienvenida
contextos/correo/infraestructura/src/bienvenida.rs EnviadorCorreoBienvenidaPlantilla, with its tests
contextos/correo/infraestructura/plantillas/bienvenida/ asunto.txt, cuerpo.html, cuerpo.txt
Mailpit added to docker-compose.yml; SMTP_URL and MAIL_FROM to .env. See the mails with `make correo/ui`.

The fields after -- are the values the text shows. They are primitives or opt:<type>, and the recipient para is always there. Every mail lives in one context, correo, with a dominio and an infraestructura crate and no use cases, so no entity can be called Correo.

  • Directorycontextos/correo/
    • dominio/src/bienvenida.rs CorreoBienvenida and the port EnviadorCorreoBienvenida
    • Directoryinfraestructura/
      • src/bienvenida.rs EnviadorCorreoBienvenidaPlantilla: renders, then sends
      • Directoryplantillas/bienvenida/
        • asunto.txt
        • cuerpo.html
        • cuerpo.txt
contextos/correo/dominio/src/bienvenida.rs (excerpt)
#[derive(Debug, Clone, PartialEq)]
pub struct CorreoBienvenida {
pub para: String,
pub nombre: String,
pub plan: Option<String>,
}
#[async_trait]
pub trait EnviadorCorreoBienvenida: Send + Sync {
async fn enviar(&self, correo: &CorreoBienvenida) -> Result<(), ErrorCorreo>;
}

The templates are minijinja, in strict mode: an unknown variable is an error, not an empty string. Wrap an optional field in a check:

contextos/correo/infraestructura/plantillas/bienvenida/cuerpo.txt
Bienvenida
Nombre: {{ nombre }}
{% if plan is not none %}Plan: {{ plan }}
{% endif %}

EnviadorCorreoBienvenidaPlantilla’s tests render every template, so a typo in one fails make test, not a customer’s inbox.

In a project with domain events, tie the mail to an event and Puerto writes the consumer that sends it:

puerto generar correo bienvenida --tras cliente_creado --para email

--para names the snapshot’s String field that holds the address. The fields come from the event’s snapshot, so you do not list them. The worker gets presentacion/worker/src/consumidores/correo_bienvenida.rs, which builds the mail from the snapshot and sends it once per event:

presentacion/worker/src/consumidores/correo_bienvenida.rs (excerpt)
let correo = match evento.tipo_evento.as_str() {
CLIENTE_CREADO => match evento.decodificar::<SnapshotCliente>() {
Ok(cliente) => CorreoBienvenida {
para: cliente.email.clone(),
nombre: cliente.nombre,
},
Err(err) => {
return ResultadoManejo::descartar(MOTIVO_PAYLOAD_INVALIDO, err.detalle);
}
},
_ => return ResultadoManejo::Ack,
};

Events are delivered at least once, so puerto_correo::enviar_una_vez keeps a correos_enviados row per event: a redelivered event does not send the mail again. A crash between the send and that row sends it twice, never zero times. A permanent SMTP failure (5xx) is dead-lettered, and a temporary one (4xx, a server that is down) is retried (ADR-0020). The first mail tied to an event adds the correos_enviados migration.

Without events, the port is there and the implementation is there, but Puerto does not wire a mailer into a use case yet. Hold an Arc<dyn EnviadorCorreoBienvenida> in the use case and test it with dominio_correo::bienvenida::dobles::MockEnviadorCorreoBienvenida. That is the piece the next phases add, for password resets.

docker-compose.yml runs Mailpit, which catches every mail sent in development. Nothing reaches a real inbox.

make correo/ui # starts the containers, prints Mailpit's address: http://localhost:8025
Variable Development Production
SMTP_URL smtp://localhost:1025 (Mailpit) your provider’s SMTP URL
MAIL_FROM no-reply@<project>.localhost a sender your domain authorizes