Cómo enviar correos electrónicos transaccionales y SMS desde Webflow Cloud (SendGrid + Twilio + Postmark)

Webflow Cloud funciona con Cloudflare Workers, un entorno de ejecución rápido y distribuido globalmente que es realmente excelente para rutas de API y lógica del lado del servidor. Tiene un detalle importante que conviene conocer de antemano: la mayoría de los SDK de correo electrónico y SMS (@sendgrid/mail, twilio, nodemailer) dependen de node:http o node:https internamente, los cuales no están disponibles en el entorno de ejecución de Workers.

La buena noticia es que la solución es sencilla: SendGrid, Postmark y Twilio exponen API REST que aceptan llamadas fetch() estándar, las cuales Workers admite de forma nativa. Sin SDK, sin dependencias de módulos de Node.js y sin errores de tiempo de ejecución. Una vez que conoces el patrón, en realidad es menos código que usar los SDK.

Esta guía muestra la implementación exacta basada en fetch para los tres servicios, con módulos auxiliares reutilizables que puedes integrar en cualquier aplicación de Next.js o Astro en Webflow Cloud.

Using Astro? The helper modules in this guide (lib/sendgrid.ts, lib/postmark.ts, lib/twilio.ts) are framework-agnostic; they're just typed fetch() wrappers. You can use them in Astro API endpoints (src/pages/api/*.ts) or server actions the same way they're used in the Next.js route handlers shown here. The environment variable and runtime patterns are identical; just swap app/api/*/route.ts for your Astro endpoint path.

¿Qué necesitas para enviar correos electrónicos y SMS desde una aplicación de Webflow Cloud?

Necesitas una aplicación de Webflow Cloud desplegada, credenciales de API de cada servicio que desees utilizar y una identidad de remitente verificada para cualquier proveedor de correo electrónico. La configuración de las variables de entorno difiere ligeramente de la de Next.js estándar; las variables de entorno de tiempo de ejecución se inyectan al momento de la solicitud, no durante la compilación, lo que afecta la forma en que inicializas los clientes.

Antes de empezar, verifica que tienes todo esto listo.

Una aplicación de Webflow Cloud con una ruta de API de Next.js

Necesitas como mínimo un proyecto de Next.js 15+ desplegado en Webflow Cloud con al menos un controlador de ruta de App Router (app/api/*/route.ts) donde llamarás a los asistentes de correo electrónico o SMS. Si aún no has inicializado un proyecto, la guía de inicio de Webflow Cloud cubre la creación del proyecto y el primer despliegue.

Credenciales de API de tu proveedor de correo electrónico o SMS

Para SendGrid, necesitas:

• Una cuenta en sendgrid.com (ahora Twilio SendGrid)
• Una clave de API con permisos de Mail Send → Full Access y un remitente verificado

Puedes verificar una dirección de remitente individual en Settings → Sender Authentication → Single Sender Verification en el panel de control de SendGrid. La autenticación de dominio es necesaria para volúmenes de producción.

Para Postmark, necesitas:

• Una cuenta en postmarkapp.com
• Un token de servidor (que se encuentra en Servers → Your Server → API Tokens)
• Una firma de remitente verificada; Postmark requiere que la dirección "De" coincida con una firma registrada

Una única dirección de correo electrónico es suficiente para realizar pruebas; se recomienda una firma de dominio para producción.

Para Twilio SMS, necesitas:

• Una cuenta en twilio.com
• Tu Account SID y Auth Token del panel de control de Twilio
• Un número de teléfono de Twilio

Las cuentas de prueba gratuitas solo pueden enviar mensajes a números de teléfono verificados. Cambia a una cuenta de pago para enviar mensajes a cualquier número.

Variables de entorno de tiempo de ejecución en Webflow Cloud

Webflow Cloud inyecta las variables de entorno en el momento de la solicitud, no durante la compilación. Esta es la diferencia clave respecto a las implementaciones estándar de Next.js: process.env.SENDGRID_API_KEY es undefined si se lee durante la inicialización del módulo, pero se completa correctamente cuando se lee dentro del cuerpo de una función durante una solicitud.

El patrón de función de fábrica maneja esto a la perfección:

// lib/sendgrid.ts — read process.env inside the function, never at module top level
export function getSendGridKey() {
  const key = process.env.SENDGRID_API_KEY;
  if (!key) throw new Error("Missing SENDGRID_API_KEY environment variable");
  return key;
}

Si llamas a const key = process.env.SENDGRID_API_KEY al principio de un módulo fuera de cualquier función, será undefined en producción. He depurado este mismo problema dos veces; el síntoma es un error 401 Unauthorized de SendGrid con una cadena de clave API vacía en los registros.

6 pasos para enviar correos electrónicos transaccionales y SMS desde una aplicación de Webflow Cloud

La implementación envuelve la API REST de cada servicio en una función auxiliar tipada que lee las credenciales en el momento de la llamada. Este patrón funciona para SendGrid, Postmark y Twilio. Una vez que los auxiliares están listos, puedes llamarlos desde cualquier manejador de rutas o acción de servidor en tu aplicación Next.js.

Los seis pasos a continuación cubren la configuración de credenciales, un auxiliar de SendGrid basado en fetch, un auxiliar de Postmark, un auxiliar de SMS de Twilio, su integración en los manejadores de rutas y la implementación.

1. Añade las credenciales de la API como variables de entorno

Antes de escribir código, configura las variables de entorno que leerán tus auxiliares.

Para el desarrollo local, añádelas a .env.local en la raíz del proyecto:

# SendGrid
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxx
SENDGRID_FROM_EMAIL=hello@yourdomain.com

# Postmark (alternative to SendGrid)
POSTMARK_API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
POSTMARK_FROM_EMAIL=hello@yourdomain.com

# Twilio SMS
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_FROM_NUMBER=+15555550100

No subas .env.local al control de versiones. Confirma que .env.local está en tu .gitignore antes de continuar.

Para producción, añádelas en el panel de control de Webflow Cloud. Ve a tu proyecto → selecciona el entorno → haz clic en Variables de entorno → Añadir variable. Activa "Secret" para cualquier valor sensible (claves API, tokens de autenticación).

Los secretos se cifran en reposo y se ocultan en el panel de control. Nunca se exponen en los resultados de la compilación ni en los registros.

SENDGRID_FROM_EMAIL y POSTMARK_FROM_EMAIL también pueden configurarse como secretos. Prefiero mantenerlos como secretos en lugar de incluirlos directamente en el código fuente, ya que las direcciones de los remitentes cambian más a menudo de lo que los desarrolladores esperan durante las migraciones de dominios de correo electrónico.

2. Crea el auxiliar de correo electrónico de SendGrid

Crea un lib/sendgrid.ts asistente que llame a la API Mail Send v3 de SendGrid usando fetch():

// lib/sendgrid.ts

interface SendEmailOptions {
  to: string;
  subject: string;
  text?: string;
  html?: string;
}

export async function sendEmailSendGrid(options: SendEmailOptions): Promise<void> {
  const apiKey = process.env.SENDGRID_API_KEY;
  const fromEmail = process.env.SENDGRID_FROM_EMAIL;

  if (!apiKey) throw new Error("Missing SENDGRID_API_KEY environment variable");
  if (!fromEmail) throw new Error("Missing SENDGRID_FROM_EMAIL environment variable");

  const { to, subject, text, html } = options;

  const content: Array<{ type: string; value: string }> = [];
  if (text) content.push({ type: "text/plain", value: text });
  if (html) content.push({ type: "text/html", value: html });

  if (content.length === 0) {
    throw new Error("SendGrid email requires at least one of: text, html");
  }

  const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      personalizations: [
        {
          to: [{ email: to }],
        },
      ],
      from: { email: fromEmail },
      subject,
      content,
    }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`SendGrid API error ${response.status}: ${errorBody}`);
  }
}

La personalizations matriz es específica de SendGrid. Es un sistema de direccionamiento por lotes. Puedes enviar una única llamada a la API a múltiples destinatarios, con diferentes variables de plantilla para cada uno. Para correos electrónicos transaccionales de un solo destinatario, solo necesitas un objeto en la matriz con una única to entrada, como se muestra arriba.

La función lee process.env dentro del cuerpo de la función. Este es el patrón correcto para Webflow Cloud; las credenciales están disponibles en el momento de la solicitud, no en el momento de la inicialización del módulo.

Un envío exitoso devuelve un HTTP 202 Accepted con un cuerpo vacío. La función lanza un error ante cualquier estado que no sea OK, lo que permite al emisor gestionar los errores usando try/catch estándar.

3. Crea el asistente de correo electrónico de Postmark

Postmark es la mejor opción cuando los clientes necesitan una alta capacidad de entrega para correos electrónicos uno a uno, como recibos, restablecimientos de contraseña y alertas de cuenta. Su seguimiento de reputación es más detallado que el de SendGrid para usos transaccionales de bajo volumen.

El modelo de autenticación difiere: Postmark usa un encabezado X-Postmark-Server-Token, no un token Bearer.

Crea :lib/postmark.ts

// lib/postmark.ts

interface PostmarkEmailOptions {
  to: string;
  subject: string;
  textBody?: string;
  htmlBody?: string;
  messageStream?: string;
}

export async function sendEmailPostmark(options: PostmarkEmailOptions): Promise<void> {
  const token = process.env.POSTMARK_API_TOKEN;
  const fromEmail = process.env.POSTMARK_FROM_EMAIL;

  if (!token) throw new Error("Missing POSTMARK_API_TOKEN environment variable");
  if (!fromEmail) throw new Error("Missing POSTMARK_FROM_EMAIL environment variable");

  const { to, subject, textBody, htmlBody, messageStream = "outbound" } = options;

  const response = await fetch("https://api.postmarkapp.com/email", {
    method: "POST",
    headers: {
      "Accept": "application/json",
      "Content-Type": "application/json",
      "X-Postmark-Server-Token": token,
    },
    body: JSON.stringify({
      From: fromEmail,
      To: to,
      Subject: subject,
      TextBody: textBody,
      HtmlBody: htmlBody,
      MessageStream: messageStream,
    }),
  });

  if (!response.ok) {
    const errorBody = await response.json() as { Message: string; ErrorCode: number };
    throw new Error(`Postmark API error ${errorBody.ErrorCode}: ${errorBody.Message}`);
  }
}

Dos cosas a tener en cuenta:

• Primero, el encabezado es X-Postmark-Server-Token, no Authorization. He visto a desarrolladores pasar minutos depurando un error 401 porque asumieron que seguiría el patrón de token Bearer. No es así.
• Segundo, los nombres de los campos están en PascalCase (From, To, Subject, HtmlBody, TextBody), coincidiendo exactamente con la especificación de la API REST de Postmark. Usa las mayúsculas y minúsculas exactas que se muestran en la documentación de Postmark; la especificación de la API no especifica un manejo de nombres de campo insensible a mayúsculas para el cuerpo JSON.

El parámetro messageStream tiene como valor predeterminado "outbound" (el flujo transaccional predeterminado de Postmark). Si has creado un flujo de difusión para correos electrónicos de marketing en el panel de Postmark, pasa su nombre aquí en su lugar.

4. Crea el asistente de SMS de Twilio

La API de mensajes de Twilio usa codificación application/x-www-form-urlencoded , no JSON. La autenticación utiliza HTTP Basic Auth con el Account SID como nombre de usuario y el Auth Token como contraseña, codificados con btoa().

Crea :lib/twilio.ts

// lib/twilio.ts

interface SendSmsOptions {
  to: string;  // E.164 format: +15555550100
  body: string;
}

export async function sendSms(options: SendSmsOptions): Promise<{ sid: string; status: string }> {
  const accountSid = process.env.TWILIO_ACCOUNT_SID;
  const authToken = process.env.TWILIO_AUTH_TOKEN;
  const fromNumber = process.env.TWILIO_FROM_NUMBER;

  if (!accountSid) throw new Error("Missing TWILIO_ACCOUNT_SID environment variable");
  if (!authToken) throw new Error("Missing TWILIO_AUTH_TOKEN environment variable");
  if (!fromNumber) throw new Error("Missing TWILIO_FROM_NUMBER environment variable");

  const { to, body } = options;

  const credentials = btoa(`${accountSid}:${authToken}`);
  const endpoint = `https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`;

  const params = new URLSearchParams();
  params.append("To", to);
  params.append("From", fromNumber);
  params.append("Body", body);

  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Authorization": `Basic ${credentials}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: params.toString(),
  });

  if (!response.ok) {
    const errorBody = await response.json() as { message: string; code: number };
    throw new Error(`Twilio API error ${errorBody.code}: ${errorBody.message}`);
  }

  const result = await response.json() as { sid: string; status: string };
  return { sid: result.sid, status: result.status };
}

La codificación  es la parte que más suele confundir a la gente. La cadena de credenciales es btoa(${accountSid}:${authToken}); Basic Auth requiere el separador de dos puntos. He visto desarrolladores que solo pasan el token de autenticación o usan la clave de API de otro servicio de Twilio.accountSid + ":" + authToken Ambos resultan en errores 401 que se ven idénticos en la respuesta.

Ambos resultan en errores 401 que se ven idénticos en la respuesta.

Los números de teléfono deben estar en formato E.164: +15555550100. El prefijo + es obligatorio. Twilio devuelve un 400 si pasas 15555550100 sin el signo más.

La función devuelve { sid, status } porque querrás el SID para el registro o la confirmación de recepción. El estado suele ser "queued" tras el éxito; la entrega es asíncrona y necesitarías un webhook para rastrear el estado final "delivered" .

5. Conecta los asistentes en los manejadores de rutas de Next.js

Con los asistentes listos, llámalos desde cualquier manejador de rutas del App Router.

Aquí tienes un manejador de formulario de contacto completo que envía un correo electrónico de confirmación a través de SendGrid y una notificación interna estilo Slack a través de SMS de Twilio:

// app/api/contact/route.ts
export const runtime = 'edge';
import { NextRequest, NextResponse } from "next/server";
import { sendEmailSendGrid } from "@/lib/sendgrid";
import { sendSms } from "@/lib/twilio";

export async function POST(request: NextRequest) {
  const { name, email, message } = await request.json();

  if (!name || !email || !message) {
    return NextResponse.json({ error: "Missing required fields" }, { status: 400 });
  }

  try {
    // Send confirmation to user
    await sendEmailSendGrid({
      to: email,
      subject: `Thanks for reaching out, ${name}`,
      html: `<p>Hi ${name},</p><p>We received your message and will respond within 24 hours.</p>`,
      text: `Hi ${name}, We received your message and will respond within 24 hours.`,
    });

    // Notify team via SMS
    const teamPhone = process.env.TEAM_PHONE_NUMBER;
    if (teamPhone) {
      await sendSms({
        to: teamPhone,
        body: `New contact form submission from ${name} (${email})`,
      });
    }

    return NextResponse.json({ success: true });
  } catch (error) {
    console.error("Notification error:", error);
    return NextResponse.json({ error: "Failed to send notification" }, { status: 500 });
  }
}

Añade export const runtime = 'edge' a cada archivo de gestión de rutas que invoque a estos asistentes. Webflow Cloud requiere esta directiva para que las rutas de la API se compilen correctamente en el entorno de ejecución de Workers. Sin ella, tus rutas no se compilarán adecuadamente.

Aquí tienes el mismo patrón utilizando Postmark para un correo electrónico de restablecimiento de contraseña desde una acción de servidor:

// app/actions/auth.ts
"use server";

import { sendEmailPostmark } from "@/lib/postmark";

export async function requestPasswordReset(email: string) {
  const resetToken = crypto.randomUUID();

  // Store resetToken in your database here...

  await sendEmailPostmark({
    to: email,
    subject: "Reset your password",
    htmlBody: `
      <p>Click the link below to reset your password. This link expires in 1 hour.</p>
      <p><a href="${process.env.APP_BASE_URL}/reset-password?token=${resetToken}">
        Reset Password
      </a></p>
    `,
    textBody: `Reset your password: ${process.env.APP_BASE_URL}/reset-password?token=${resetToken}`,
  });

  return { success: true };
}

Las acciones de servidor se ejecutan en el mismo entorno de Workers que los gestores de rutas. La directiva "use server" funciona correctamente con Webflow Cloud. No hay nada especial que configurar. Las variables de entorno son accesibles de la misma manera.

6. Despliega y verifica

Despliega en Webflow Cloud con:

webflow cloud deploy

Tras el despliegue, prueba cada asistente activando la ruta o acción que lo invoca. Para el correo electrónico, revisa tu bandeja de entrada de inmediato. Para SMS, comprueba el teléfono de destino. Si usas SendGrid, consulta el registro de Actividad → Actividad de correo electrónico en el panel de control de SendGrid. Cada intento de envío se registra con su estado completo en cuestión de segundos.

Para SMS de Twilio, revisa la vista Monitor → Logs → Messages en la consola de Twilio. Cada mensaje muestra la progresión del estado desde queued → sent → delivered.

Algo que siempre hago antes de cualquier despliegue a producción: probar primero con mi propio correo y número de teléfono. El modo sandbox de SendGrid solo valida la estructura JSON; devuelve un 200 OK y nunca entrega el correo, consume créditos ni genera actividad en el Webhook de eventos.

Eso lo hace útil para comprobar el formato, pero inútil para verificar que tus credenciales, la identidad del remitente y la autenticación del dominio funcionan. Un envío real a una bandeja de entrada real es la única forma de verificar la entrega de extremo a extremo.

¿Qué causa que el correo electrónico transaccional y los SMS fallen en Webflow Cloud?

Los fallos comunes se dividen en tres categorías: errores de módulos SDK de paquetes que no funcionan en el entorno de ejecución de Workers, errores de autenticación por variables de entorno mal configuradas y errores de entrega por requisitos de verificación del remitente.

Aquí te explicamos cómo diagnosticar y solucionar cada uno.

El paquete SDK lanza "Module not found" o "node:https is not defined"

Este error significa que tienes importado un SDK de correo o SMS que depende de módulos de Node.js no disponibles. El error aparece en tiempo de ejecución en Webflow Cloud, incluso si tu desarrollo local funciona perfectamente.

Causa: @sendgrid/mail, twilio, postmark, nodemailer, o cualquier paquete que envuelva node:http/node:https internamente.

Solución: Elimina el paquete SDK de tus importaciones y sustitúyelo por el asistente basado en fetch de esta guía. Ejecuta npm uninstall @sendgrid/mail (o el paquete correspondiente) para eliminar la dependencia por completo. Los paquetes no utilizados que importan node:http pueden seguir causando errores si se incluyen en el paquete final.

SendGrid devuelve 401 Unauthorized

Causa 1:SENDGRID_API_KEY lectura al nivel superior del módulo. Si tienes const apiKey = process.env.SENDGRID_API_KEY, al usarse fuera de cualquier función, se evalúa como undefined en el entorno de ejecución de Webflow Cloud. La clave no se inyecta hasta el momento de la solicitud.

Solución: Mueve todas las lecturas de process.env dentro de los cuerpos de las funciones. El patrón de asistente del paso 2 maneja esto correctamente.

Causa 2: La clave de API no tiene permisos de envío de correo (Mail Send). Una clave de API recién creada tiene acceso restringido por defecto. Verifica si Mail Send → Full Access está configurado en los ajustes de claves de API de SendGrid.

Causa 3: Remitente no verificado. SendGrid rechaza los envíos desde direcciones de remitente no verificadas con una respuesta 403 Forbidden. Completa la verificación de remitente único o la autenticación de dominio antes de realizar pruebas.

Twilio devuelve un error 401 o 20003 de autenticación

btoa()Causa: se llamó con el formato de cadena incorrecto. Un error común es pasar en lugar de .btoa(authToken)btoa(${accountSid}:${authToken})

Solución: verifica que la cadena de credenciales incluya el separador de dos puntos: ${accountSid}:${authToken}`) TWILIO_ACCOUNT_SID AC; ese prefijo confirma que es el SID de la cuenta, no una credencial secundaria como un SID de servicio de mensajería.btoa(\. Check thatstarts with

Además, confirma que estás leyendo , no . Twilio tiene varios tipos de credenciales; la API REST para el envío básico de mensajes utiliza el SID de la cuenta y el token de autenticación que aparecen en la parte superior del panel de control de Twilio.TWILIO_AUTH_TOKENTWILIO_API_KEY

Postmark devuelve un error 422 ('Sender signature not verified')

Causa: la dirección "De" (From) en tu carga útil no coincide con una firma de remitente verificada en tu cuenta de Postmark. Postmark devuelve un error HTTP 422 con el código 300: "Invalid 'From' address: '[tu-dirección]' is not a verified sender signature."

Solución: inicia sesión en el panel de control de Postmark, navega a Sender Signatures y verifica que tu dirección de correo electrónico "De" esté registrada y confirmada. La dirección debe coincidir exactamente: y son firmas distintas.hello@yourdomain.comnoreply@yourdomain.com

Si cambiaste recientemente , la nueva dirección necesita su propia firma. Postmark envía un correo electrónico de confirmación para verificar la propiedad.POSTMARK_FROM_EMAIL

Los mensajes SMS están en cola pero no se entregan

Causa 1: restricción de cuenta de prueba. Las cuentas de prueba gratuitas de Twilio solo pueden enviar mensajes a identificadores de llamadas verificados. Verás el mensaje atascado en estado con una nota de error en la consola.queued

Solución: añade el número de destino a los identificadores de llamadas verificados en la consola de Twilio o actualiza a una cuenta de pago.

Causa 2: formato E.164 no válido para o números. Los números de teléfono sin el prefijo son rechazados silenciosamente en algunas regiones, o aceptados pero no entregados.tofrom+

Solución: asegúrate de que tanto como sigan el formato E.164: seguido del código de país y el número sin espacios ni guiones.ToFrom+

Los correos electrónicos llegan a spam después de la implementación

Causa: envío desde un dominio no autenticado. Tanto SendGrid como Postmark requieren autenticación de dominio (registros DKIM/SPF) para establecer la reputación del remitente. Sin esto, los principales proveedores de correo aplican filtros de spam estrictos.

Solución: completa la autenticación de dominio en SendGrid (en Settings → Sender Authentication) o añade una firma de dominio en Postmark. Ambos servicios proporcionan registros DNS que puedes añadir a tu registrador de dominios. La propagación completa tarda hasta 48 horas, pero la mayoría de los registros se propagan en una hora.

Crea flujos de notificación completos en Webflow Cloud

Los asistentes de esta guía cubren los elementos básicos: un envío de correo confirmado y un SMS despachado. Los flujos de notificación reales añaden lógica de reintento, seguimiento de entrega y enrutamiento multicanal: enviar primero por correo, recurrir a SMS si el correo rebota, registrar todos los envíos en una base de datos para auditorías.

Para aplicaciones que necesitan el correo electrónico como una función orientada al usuario en lugar de solo una herramienta interna, la página de integración de Webflow con SendGrid cubre cómo se conecta SendGrid con los datos de formularios y CMS de Webflow.

Para aplicaciones donde envuelves APIs externas en una interfaz consistente, consulta la guía sobre cómo crear envoltorios de API en Webflow Cloud; el mismo patrón de función de fábrica utilizado para los asistentes de correo electrónico se aplica a cualquier integración de terceros.

Explora la documentación para desarrolladores de Webflow para obtener una personalización más profunda, renderizado dinámico de plantillas, seguimiento de entregas mediante webhooks y enlaces a Workers disponibles en Webflow Cloud.