Enviar correo desde un Worker: el binding y el proveedor

Recibir correo con código era, al final, un problema de parseo. Enviarlo es un problema de reputación. Puedes emitir un mensaje impecable, con las cabeceras correctas y un cuerpo limpio, y que aterrice en la carpeta de basura de tu usuario porque un filtro que no controlas decidió que tu dominio todavía no se ha ganado el derecho a hablar. Por eso esta lección tiene dos mitades desiguales: la mecánica de emitir, que se resuelve en veinte líneas, y la disciplina de que llegue, que se gana con meses de comportarse bien.

Dos puertas que no son intercambiables

La primera decisión no es técnica, es de destinatario. Cloudflare ofrece un binding de envío que emite correo directamente desde el Worker, pero con una restricción deliberada: solo entrega a direcciones de destino verificadas en tu propia cuenta. No es una limitación que puedas sortear, es el diseño. Sirve para que tu sistema te hable a ti.

El proveedor externo por API es la otra puerta. Una llamada fetch autenticada contra un servicio especializado que se encarga de la infraestructura de envío, la reputación de las direcciones IP, los rebotes y las bajas. Es el camino obligado cuando el destinatario es un usuario cualquiera, es decir, casi siempre que el correo forme parte del producto.

El binding de envío

Se declara en el manifiesto como cualquier otro binding, y se ata a la dirección de destino que ya has verificado.

{
  "send_email": [
    { "name": "CORREO", "destination_address": "equipo@ejemplo.com" }
  ]
}

El objeto que se envía es un EmailMessage construido a partir del mensaje crudo en formato RFC 5322. Componer ese texto a mano es un ejercicio de precisión innecesario: una librería como mimetext lo ensambla bien, con sus cabeceras y su codificación.

import { EmailMessage } from "cloudflare:email";
import { createMimeMessage } from "mimetext";

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const msg = createMimeMessage();
    msg.setSender({ name: "Alertas", addr: "alertas@ejemplo.com" });
    msg.setRecipient("equipo@ejemplo.com");
    msg.setSubject("Umbral de errores superado");
    msg.addMessage({
      contentType: "text/plain",
      data: "La tasa de 5xx lleva diez minutos por encima del dos por ciento.",
    });

    const aviso = new EmailMessage("alertas@ejemplo.com", "equipo@ejemplo.com", msg.asRaw());
    ctx.waitUntil(env.CORREO.send(aviso));

    return new Response("recibido", { status: 202 });
  },
} satisfies ExportedHandler<Env>;

La dirección remitente debe pertenecer a un dominio de tu cuenta, y la destinataria tiene que coincidir con la verificada. Fuera de eso, el envío es una llamada más al env, con la misma ergonomía que escribir en KV.

El proveedor externo por API

Aquí no hay binding, hay una petición HTTP saliente y una clave que jamás debe vivir en el código. La clave es un secreto cifrado del Worker, y el patrón es el de cualquier subpetición.

async function enviar(env: Env, destino: string, asunto: string, html: string) {
  const respuesta = await fetch("https://api.proveedor.com/v1/emails", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${env.CLAVE_CORREO}`,
      "Content-Type": "application/json",
      "Idempotency-Key": await claveIdempotente(destino, asunto),
    },
    body: JSON.stringify({
      from: "Producto <hola@ejemplo.com>",
      to: destino,
      subject: asunto,
      html,
    }),
  });

  if (!respuesta.ok) {
    throw new Error(`envio fallido: ${respuesta.status}`);
  }
}

Dos detalles que separan un envío ingenuo de uno correcto. El primero es la cabecera de idempotencia: si el Worker reintenta, o si una cola vuelve a entregar el mensaje, el proveedor debe reconocer que ya emitió ese correo y no duplicarlo. El segundo es el manejo del fallo, porque una API de correo caída es una eventualidad ordinaria, no una excepción.

flowchart LR
H[handler HTTP] --> Q[Queue de correo]
Q --> C[consumidor con reintentos]
C --> B[binding de envio]
C --> P[API del proveedor]
C --> DLQ[cola de fallidos]
style Q fill:#89b4fa,color:#11111b
style DLQ fill:#f38ba8,color:#11111b

Que salga y que además llegue

Emitir es la mitad barata. La otra mitad se gana con cuatro disciplinas.

Y una disciplina más, esta puramente arquitectónica: el envío no va en el camino crítico. Si tu handler espera a que el proveedor responda antes de contestar al usuario, has atado la latencia de tu formulario a la disponibilidad de un tercero, y has convertido su caída en tu error 500. Encola el envío o suéltalo con waitUntil, contesta al usuario de inmediato y deja que un consumidor con reintentos y cola de fallidos se ocupe de la entrega.