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✓ 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.
The three pieces
Section titled “The three pieces”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
#[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:
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.
Sending it when something happens
Section titled “Sending it when something happens”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:
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.
Sending from a use case
Section titled “Sending from a use case”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.
Development and production
Section titled “Development and production”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 |