Seguiremos dos casos: iniciar sesión con un código de un solo uso y recibir la confirmación de una reserva. El primero necesita un mensaje claro y un campo de entrada adecuado. El segundo añade un logotipo, un billete PDF, metadatos de Gmail y un archivo de calendario. Veremos qué hace el servidor, qué decide el cliente de correo y cómo comprobar cada parte.

Empieza por tu caso: correo con código, confirmación con adjuntos, reserva en Gmail, promoción o evento de calendario. Después se explican el campo web y WebOTP, Android e iPhone. Son integraciones distintas: implementar una no activa las demás.

Actualizado el 12 de noviembre de 2026. Se añaden un ejemplo completo de correo, generación local de .eml, explicación de campos de Gmail y ciclo de una invitación de calendario.

Copiar, autocompletar y verificar son tres tareas distintas

El reconocimiento encuentra el código en el mensaje. El autocompletado lo sugiere o lo introduce en el campo adecuado. La verificación del servidor decide si ese código confirma una acción concreta. Un botón cómodo no sustituye la vinculación al intento de acceso ni la comprobación de la caducidad.

Un OTP es un código de un solo uso, no necesariamente un «segundo factor». Los códigos para confirmar una dirección, acceder sin contraseña y realizar una verificación adicional después de introducirla pueden tener el mismo aspecto. La interfaz debe explicar la finalidad de la acción y la arquitectura debe distinguir estos casos.

Mensaje con código, sugerencia del sistema, campo y verificación del servidor: etapas independientes
Modelo de trabajo: reconocer el código no basta. Hay que conservar su relación con la finalidad para la que se emitió. Es un diagrama del proceso, no una captura de un sistema operativo concreto.

Qué ha cambiado en Gmail y qué no garantiza

En septiembre de 2026, medios especializados informaron de un botón para copiar OTP en Gmail para móviles. Android Authority describe el botón justo debajo del asunto en la bandeja de entrada. Las observaciones corresponden a Android e iOS. Es información sobre el despliegue de una función, no un contrato publicado para desarrolladores.

Botón Copy code bajo el asunto de un correo de Humble Bundle en la bandeja de Gmail
Copiar el código sin abrir el correo. El botón azul Copy code aparece bajo el asunto en la bandeja. El autor de la captura ocultó las cifras. Muestra un comportamiento observado del cliente, no un botón HTML añadido por el remitente. Fuente: Hadlee Simons / Android Authority.

Por eso, la especificación del producto no puede prometer: «Todos tendrán Copy code en Gmail». El reconocimiento depende del correo y de la disponibilidad de la función. No debe extrapolarse lo observado en la lista de mensajes a una notificación push, a Gmail web ni a cualquier otro cliente de correo. Para un servicio propio basta con que el mensaje se entienda sin un botón especial.

Plantilla propuesta: asunto «Código de acceso a Example», un único código bien visible, finalidad de la acción, plazo de validez y explicación de qué hacer si la persona no solicitó el acceso. Evitad números de pedido de seis cifras que se parezcan al código, bloques publicitarios innecesarios o un código disponible solo como imagen. Añadid la parte de texto del mensaje MIME y comprobad el resultado real en los clientes utilizados. Son recomendaciones de claridad, no un método documentado para activar por la fuerza el botón de Gmail.

Text
Código de acceso a Example

482913

Has solicitado acceder a tu cuenta en example.com.
El código es válido durante 5 minutos. No lo compartas con otras personas.
Si no has sido tú, no confirmes el acceso.

El ejemplo es ilustrativo: cinco minutos es la política elegida por el servicio, no un límite general de Gmail. En un producto real, el plazo indicado en el correo debe coincidir con la política del servidor.

Summary Cards, Email Markup y OTP no son una única API

Gmail también puede mostrar otros datos útiles. La ayuda de Google sobre Summary Cards enumera seguimiento de pedidos, eventos, viajes, facturas y ofertas. La visualización depende, entre otras cosas, de los ajustes de funciones inteligentes y de que el correo contenga datos suficientes. La tarjeta de resumen forma parte de la interfaz del cliente de correo.

Cuatro ejemplos de Gmail con tarjetas de entrega, evento, factura y vuelo sobre el contenido del correo
La tarjeta está encima del contenido del correo. De izquierda a derecha: entrega, evento con entrada, factura y vuelo. En la segunda pantalla, fecha, lugar y View ticket están separados del diseño del mensaje. Ilustración oficial de Google publicada en 2024; la interfaz puede cambiar. Fuente: Google.
MecanismoQué haceQué puede controlar el remitente
Reconocimiento de OTPPuede identificar el código y ofrecer copiarloLa claridad del correo. No se ha confirmado un interruptor público para Copy code
Summary CardsResume datos de pedidos, viajes y otros eventosDatos correctos y coherentes en los correos
Email Markup / HighlightsDescribe entidades y acciones compatiblesEl marcado, la autenticación del remitente y el proceso de admisión
Gmail APIProporciona acceso autorizado a los datos del buzónLa integración OAuth de su aplicación y el tratamiento de los datos autorizados

Gmail Email Markup utiliza Schema.org y los formatos compatibles JSON-LD y Microdata para entidades como pedidos, envíos y reservas. No permite declarar un objeto OTP arbitrario y obtener autocompletado garantizado. Para enviar correos con marcado, Google exige registrar al remitente y cumplir requisitos de calidad y autenticación de los mensajes. Un JSON válido no garantiza por sí solo una interfaz especial para el destinatario.

En el recurso documentado Gmail API Message , el campo snippet es un fragmento breve de texto. No debe interpretarse como un OTP extraído ni como el resultado de Summary Cards. En la documentación revisada no se encontró un método público específico para obtener un código o una tarjeta reconocidos por Gmail. Las etiquetas de clasificación de Workspace tampoco implican que la API devuelva OTP.

Construir un mensaje claro a partir de la reserva

Alex ha reservado un taller de cerámica para el 21 de noviembre, de 10:00 a 12:00 en Praga. La confirmación debe responder enseguida: ¿está confirmada la plaza?, ¿cuándo debe llegar?, ¿dónde es?, ¿dónde está la entrada? Las respuestas deben seguir disponibles sin tarjetas de Gmail ni imágenes cargadas.

El contenido que ve el destinatario en el correo de demostración:

Booking WS-1042 confirmed

Hello, Alex Morgan.

Ceramics workshop
21 November 2026, 10:00–12:00 (Europe/Prague)
Example Studio
Example Street 12, 110 00 Prague, Prague, CZ

Your PDF ticket is attached.

Los nombres, direcciones, dominios y reservas del ejemplo son ficticios. El correo de demostración está en inglés en todas las ediciones para mantener el mismo código. Es un módulo Node.js para un proyecto que ya tenga Nodemailer instalado. Genera un preview.eml local sin enviar nada. Guarda los dos bloques siguientes, en orden, como email-demo.mjs.

JavaScript
import nodemailer from "nodemailer";
import { readFile, writeFile } from "node:fs/promises";

const booking = {
  id: "WS-1042", name: "Alex Morgan", event: "Ceramics workshop",
  start: "2026-11-21T10:00:00+01:00", end: "2026-11-21T12:00:00+01:00",
  when: "21 November 2026, 10:00–12:00 (Europe/Prague)",
  venue: "Example Studio", street: "Example Street 12",
  city: "Prague", region: "Prague", postalCode: "110 00", country: "CZ"
};
const escapeHtml = value => String(value).replace(/[&<>"']/g,
  c => ({"&":"&amp;", "<":"&lt;", ">":"&gt;", '"':"&quot;", "'":"&#39;"})[c]);
const address = `${booking.street}, ${booking.postalCode} ${booking.city}, ${booking.region}, ${booking.country}`;
const text = `Booking ${booking.id} confirmed\n\nHello, ${booking.name}.\n${booking.event}\n${booking.when}\n${booking.venue}: ${address}\nYour PDF ticket is attached.`;
let html = `<!doctype html><html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
</head><body style="margin:0;padding:24px;background:#ffffff;color:#202020;font-family:Arial,sans-serif">
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td>
<img src="cid:brand-logo@example.com" width="160" height="48" alt="Example Studio" style="display:block;border:0">
<h1 style="font-size:24px;line-height:32px">Booking ${escapeHtml(booking.id)} confirmed</h1>
<p>Hello, ${escapeHtml(booking.name)}.</p>
<p><strong>${escapeHtml(booking.event)}</strong><br>${escapeHtml(booking.when)}</p>
<p>${escapeHtml(booking.venue)}<br>${escapeHtml(address)}</p>
<p>Your PDF ticket is attached.</p>
</td></tr></table></body></html>`;

booking aporta los datos al texto, HTML, Gmail y calendario. En producción procede de una reserva validada en la base de datos; when se calcula a partir de la fecha y zona horaria, no se mantiene por separado. escapeHtml convierte caracteres como < en texto para que un nombre no se interprete como una etiqueta. text es una versión legible que el cliente puede elegir en lugar del HTML.

ElementoFunciónComprobación
h1, p, br, strong, a, ul, liTexto, jerarquía y enlacesEl mensaje tiene sentido sin estilos; las acciones usan enlaces HTTPS normales.
table, tr, tdDistribución predeciblerole="presentation" para maquetación; conservar la semántica de las tablas de datos.
imgLogotipo o ilustraciónProporciones, dimensiones y alt correctos. Fechas, precios y códigos siguen siendo texto.
CSS inlineEspaciado, colores y tipografía esencialesEl contenido principal no depende de CSS externo, flex/grid ni imágenes de fondo.
script, iframe, formEvitar para interacciones de correo convencionalesJSON-LD es un bloque de datos específico, no permiso para ejecutar JavaScript.

Es una base conservadora, no una certificación universal. Gmail admite ciertos bloques style y media queries, pero eso no demuestra compatibilidad con Outlook clásico. Consulta una propiedad concreta en la referencia CSS de Gmail. Prueba el mensaje recibido en una pantalla estrecha, con modo oscuro y sin imágenes.

Añadir logotipo y PDF: HTML es solo una parte del mensaje

cid:brand-logo@example.com apunta a una parte del propio mensaje. Nodemailer la vincula con el PNG que tenga exactamente ese cid. El PDF queda como archivo descargable independiente. Añade el segundo bloque y ejecuta node email-demo.mjs ./logo.png ./ticket.pdf con tu PNG de 160×48 y un PDF de prueba sin datos personales.

JavaScript
const [logoPath, ticketPath] = process.argv.slice(2);
if (!logoPath || !ticketPath) throw new Error("Pass a PNG logo and a PDF ticket");
const [logo, ticket] = await Promise.all([readFile(logoPath), readFile(ticketPath)]);
if (!logo.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10]))) {
  throw new Error("Logo is not a PNG");
}
if (ticket.subarray(0, 5).toString() !== "%PDF-") throw new Error("Ticket is not a PDF");
const message = {
  from: "Example Studio <booking@example.com>", to: "alex@example.com",
  subject: `Booking ${booking.id} confirmed`, text, html,
  attachments: [
    { filename: "logo.png", content: logo, contentType: "image/png",
      cid: "brand-logo@example.com", contentDisposition: "inline" },
    { filename: `ticket-${booking.id}.pdf`, content: ticket,
      contentType: "application/pdf", contentDisposition: "attachment" }
  ]
};
const previewTransport = nodemailer.createTransport({
  streamTransport: true, buffer: true, newline: "windows"
});
const result = await previewTransport.sendMail(message);
await writeFile("preview.eml", result.message);

Abre preview.eml como archivo local en un cliente de correo: deberían aparecer el mensaje, el logotipo y el PDF. Esto comprueba la composición, no la entrega. Las firmas detectan tipos de archivo equivocados, pero no validan el contenido del PDF ni que la entrada pertenezca al destinatario. Si falla la lectura del archivo, la composición se detiene: no se genera un mensaje que promete una entrada adjunta sin incluirla.

MIME agrupa varias partes en un mensaje. Esta es una estructura válida; la biblioteca genera los delimitadores y la codificación:

Text
multipart/mixed
├── multipart/alternative
│   ├── text/plain; charset=utf-8
│   └── multipart/related
│       ├── text/html; charset=utf-8
│       └── image/png; Content-ID: <brand-logo@example.com>
└── application/pdf; filename=ticket-WS-1042.pdf

alternative ofrece dos versiones del mismo contenido, related relaciona HTML e imagen, y mixed añade un documento independiente. Cambiar la extensión a .pdf no basta: importan los bytes y Content-Type. Mide el mensaje codificado: base64 aumenta aproximadamente un tercio el tamaño del archivo. Genera la entrada de cada destinatario; no envíes documentos personales a una lista BCC compartida.

Este logotipo aparece dentro del cuerpo. Una imagen HTTPS pública y estable puede sustituir a CID cuando sea adecuado publicarla, pero el cliente puede bloquear cualquiera de las dos. El logotipo junto a una promoción usa los metadatos que veremos después. El avatar del remitente mediante BIMI depende del dominio y de los requisitos del proveedor: un PNG en HTML no lo activa. No publiques un PDF privado para conseguir una URL cómoda. Consulta el API utilizado en adjuntos de Nodemailer y stream transport.

Describir la reserva para Gmail

La persona lee «taller, 21 de noviembre, 10:00». Los metadatos expresan lo mismo para una máquina: la reserva confirmada WS-1042 pertenece a Alex y corresponde a un evento en una dirección concreta. Gmail puede usar estos datos en sus funciones de reservas. No estás dibujando esa interfaz ni ordenando añadir un evento al calendario.

Tarjeta de reserva de restaurante en Gmail antes y después, con hora, dirección y botones
Qué destaca Gmail de una confirmación. A la derecha resaltan fecha y hora, seguidas del lugar y las acciones Invite others, Call y Modify booking. La comparación de Google de 2024 muestra un restaurante. Ilustra la interfaz, no el resultado de nuestro EventReservation; los restaurantes utilizan otro tipo de esquema. Fuente: Google.

Inserta este bloque entre el primero y el segundo del ejemplo, antes de construir message. Añade JSON-LD al head del correo. El JSON no debe aparecer como texto visible. Cambiar el marcado SEO de la web o adjuntar un archivo JSON independiente no realiza esta integración.

JavaScript
function emailJsonLd(data) {
  const json = JSON.stringify(data);
  if (json === undefined) throw new Error("Missing structured data");
  return '<script type="application/ld+json">' + json
    .replace(/</g, "\\u003c")
    .replace(/>/g, "\\u003e")
    .replace(/&/g, "\\u0026")
    .replace(/\u2028/g, "\\u2028")
    .replace(/\u2029/g, "\\u2029") + '</script>';
}
const reservation = {
  "@context": "http://schema.org", "@type": "EventReservation",
  reservationNumber: booking.id,
  reservationStatus: "http://schema.org/ReservationConfirmed",
  underName: { "@type": "Person", name: booking.name },
  reservationFor: {
    "@type": "Event", name: booking.event,
    startDate: booking.start, endDate: booking.end,
    location: {
      "@type": "Place", name: booking.venue,
      address: {
        "@type": "PostalAddress", streetAddress: booking.street,
        addressLocality: booking.city, addressRegion: booking.region,
        postalCode: booking.postalCode, addressCountry: booking.country
      }
    }
  }
};
html = html.replace("</head>", emailJsonLd(reservation) + "</head>");

reservationNumber identifica la reserva; underName, a su titular; reservationFor, el evento. +01:00 hace inequívoca la hora de esa fecha de noviembre. Incluimos la dirección completa porque Google la exige para este tipo. Si la base de datos solo tiene una ciudad, consigue primero la dirección real del lugar: no inventes campos obligatorios. El contrato EventReservation define los campos.

El nombre del evento puede contener comillas o un </script> literal. JSON.stringify produce JSON válido; sustituir < por \u003c evita que el valor cierre el bloque HTML. Al interpretar el JSON se recupera el nombre original. &quot; no sustituye las comillas JSON: las estropearía. Este es el formato JSON-LD para correo, no un script ejecutable.

Comprueba cuatro capas: interpreta el JSON final; contrasta reserva, titular, hora y dirección con el texto visible; valida el HTML en Email Markup Tester; inspecciona un mensaje recibido. Google permite pruebas con la misma cuenta como remitente y destinatario, pero sigue exigiendo SPF o DKIM. Para producción existe un registro separado. Un .eml local válido no demuestra que los clientes vean tarjetas. Continúa con las pruebas de esquemas y los requisitos de registro.

Promotions: describir una oferta, no un código de acceso

Otro caso: la persona todavía no ha reservado. Ofreces «60 € → 45 €, código CLAY15, hasta el 20 de noviembre». La anotación describe imagen, oferta y vencimiento para Promotions. Las mismas condiciones deben figurar en el texto visible; la suscripción y la baja siguen siendo parte del sistema de envíos.

Fila de correo en Promotions con la etiqueta 20% Off y el código 20TODAY
DiscountOffer: una etiqueta breve bajo el asunto. Se ven el 20% de descuento y el código 20TODAY. Es un código promocional de compra, no de acceso. La oferta se puede ver sin abrir el correo. Fuente: Google Developers.
Promoción de Gmail con logotipo Motto, descuento, código e imagen grande del producto
PromotionCard muestra la oferta visualmente. Bajo el remitente y el asunto aparecen una imagen y su descripción. La anotación aporta la URL pública de la imagen. Es una vista previa en la bandeja, no una imagen dentro del cuerpo del mensaje. Fuente: Google Developers.

Este objeto corresponde a un correo promocional separado, no a la confirmación. Reutiliza emailJsonLd. Todas las URL example.com son marcadores ilustrativos: sustitúyelas por recursos y destinos HTTPS públicos y comprobados antes del envío.

JavaScript
const promotion = [
  { "@context": "http://schema.org/", "@type": "Organization",
    logo: "https://example.com/assets/logo.png" },
  { "@context": "http://schema.org/", "@type": "DiscountOffer",
    description: "Save €15 on the ceramics workshop", discountCode: "CLAY15",
    availabilityStarts: "2026-11-12T09:00:00+01:00",
    availabilityEnds: "2026-11-20T23:59:00+01:00" },
  { "@context": "http://schema.org/", "@type": "PromotionCard",
    image: "https://example.com/assets/workshop.jpg",
    url: "https://example.com/offers/ceramics",
    headline: "Ceramics workshop", price: "60", priceCurrency: "EUR",
    discountValue: "15" }
];
// In a separate promotional email, before building its message object:
html = html.replace("</head>", emailJsonLd(promotion) + "</head>");

price: "60" es el precio original y discountValue: "15" es el importe que se resta: 45 €, no un 15% de descuento. El checkout debe aceptar CLAY15 y la fecha del servidor debe coincidir con availabilityEnds. PromotionCard requiere imagen y URL de destino. Usa PNG/JPEG con proporción 4:5, 1:1 o 1.91:1. Una imagen CID no sustituye a una URL pública. Las anotaciones válidas no eligen la pestaña de destino ni garantizan su visualización. Consulta el mecanismo Promotions y la definición de campos.

Carrusel de Promotions con productos, nombres y precios originales y rebajados
Varios objetos PromotionCard forman un carrusel. Una vista previa puede incluir varias ofertas, cada una con imagen, nombre y precio. Es otra modalidad de anotación; para el taller del ejemplo basta una tarjeta. Fuente: Google Developers.

event.ics: elegir entre importar un evento o enviar una invitación

Un taller comprado suele necesitar un enlace «Añadir al calendario» o un archivo importable. Eso crea una copia en el calendario del destinatario. Cambiar luego tu base de datos no garantiza que esa copia se actualice. Para Aceptar/Rechazar, reprogramar y cancelar necesitas un intercambio de invitaciones y procesar respuestas, no cambiar el nombre del archivo.

Este es un archivo mínimo para importar el evento. DTSTART:20261121T090000Z representa las 09:00 UTC, las 10:00 de Praga ese día. DTEND indica el final; UID es la identidad persistente del evento; DTSTAMP indica cuándo se produjeron los datos, no cuándo empieza el taller.

Text
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Studio//Booking//EN
CALSCALE:GREGORIAN
BEGIN:VEVENT
UID:booking-WS-1042@example.com
DTSTAMP:20261112T120000Z
DTSTART:20261121T090000Z
DTEND:20261121T110000Z
SUMMARY:Ceramics workshop
LOCATION:Example Studio\, Example Street 12\, Prague
DESCRIPTION:Booking WS-1042\nBring your PDF ticket.
END:VEVENT
END:VCALENDAR

Usa finales de línea CRLF y un CRLF final. Escapa comas, puntos y coma, barras inversas y saltos dentro de valores de texto. Divide las líneas largas por bytes UTF-8: slice(0, 75) puede romper contenido multilingüe. Añade el código después de construir message y antes de previewTransport.sendMail:

JavaScript
const escapeIcsText = value => String(value).replace(/\\/g, "\\\\")
  .replace(/;/g, "\\;").replace(/,/g, "\\,").replace(/\r\n|\r|\n/g, "\\n");
function foldIcsLine(line) {
  let result = "", bytes = 0;
  for (const character of line) {
    const length = Buffer.byteLength(character, "utf8");
    if (bytes + length > 75) { result += "\r\n "; bytes = 1; }
    result += character; bytes += length;
  }
  return result;
}
const utc = value => new Date(value).toISOString()
  .replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
const calendar = [
  "BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//Example Studio//Booking//EN",
  "CALSCALE:GREGORIAN", "BEGIN:VEVENT", `UID:booking-${booking.id}@example.com`,
  `DTSTAMP:${utc(new Date())}`, `DTSTART:${utc(booking.start)}`, `DTEND:${utc(booking.end)}`,
  `SUMMARY:${escapeIcsText(booking.event)}`,
  `LOCATION:${escapeIcsText(booking.venue + ", " + address)}`,
  `DESCRIPTION:${escapeIcsText("Booking " + booking.id + "\nBring your PDF ticket.")}`,
  "END:VEVENT", "END:VCALENDAR"
].map(foldIcsLine).join("\r\n") + "\r\n";
message.attachments.push({ filename: "event.ics", content: Buffer.from(calendar),
  contentType: "text/calendar; charset=utf-8", contentDisposition: "attachment" });

Z significa UTC. Guarda una zona IANA como Europe/Prague y calcula el desplazamiento para la fecha del evento: en verano es +02:00. No uses la zona del servidor. Comprueba que el final sea posterior al inicio y resuelve expresamente horas inexistentes por cambios de horario. Los eventos de día completo usan VALUE=DATE: finalizar el 22 de noviembre incluye el 21 como último día. iCalendar define estas reglas.

Una invitación añade estos campos a los mismos datos del evento. Es un fragmento de cambios, no un archivo completo; los puntos suspensivos representan el resto. Usa organizador y participante reales. PARTSTAT=NEEDS-ACTION significa que no hay respuesta todavía; no marques ACCEPTED en nombre de la persona.

Text
METHOD:REQUEST
...
UID:booking-WS-1042@example.com
SEQUENCE:0
ORGANIZER:mailto:events@example.com
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:mailto:alex@example.com

METHOD:REQUEST dentro del calendario debe coincidir con Content-Type: text/calendar; charset=utf-8; method=REQUEST en MIME. Nodemailer ofrece icalEvent: { method: "REQUEST", content: requestCalendar }. Úsalo en lugar del adjunto de calendario convencional y evita PDF e imágenes adicionales que dificultan su reconocimiento en algunos clientes. requestCalendar debe contener un calendario completo válido. El API de Nodemailer lo empaqueta, pero no implementa tu sistema de planificación.

AcciónEnvíoEstado del servidor
Invitación inicialREQUEST, UID booking-WS-1042@example.com, SEQUENCE:0Organizador, participante, hora y versión.
Cambio a las 11:00REQUEST, mismo UID, SEQUENCE:1, nuevos DTSTART/DTEND y DTSTAMPAumentar versión por el cambio, no por cada reintento de entrega.
Cancelar tras el cambioCANCEL, mismo UID, SEQUENCE:2, STATUS:CANCELLEDGuardar cancelación y destinatarios; el método MIME también es CANCEL.
Respuesta del participanteREPLY, mismo UID, versión correspondiente y PARTSTAT del participanteVerificar remitente, participante y versión antes de guardar la respuesta.

iMIP, RFC 6047 relaciona los métodos de calendario con el correo; iTIP, RFC 5546 define los intercambios. ATTENDEE en un archivo recibido no demuestra la identidad del remitente. Incluso con un UID estable, comprueba importación repetida, cambios y cancelación en los calendarios objetivo: interpretar el archivo no demuestra cómo se comportará el cliente.

Localizar la capa que ha fallado

SíntomaComprobaciónCorrección
Falta el logotipoComparar cid del HTML y Content-ID del original; activar imágenes.Corregir CID o estructura related; conservar marca textual y alt.
Falta la entrada prometidaRevisar generación del PDF y application/pdf en MIME recibido.Componer solo cuando termine la generación; no prometer adjuntos ausentes.
No aparece tarjeta GmailComprobar JSON-LD después del proveedor, campos y admisión del remitente.Corregir esa capa; el tamaño de letra no arregla metadatos.
Evento una hora antesComparar fecha, zona IANA, desplazamiento y DTSTART.Calcular UTC para esa fecha; alinear texto, HTML e ICS.
Duplicado al reprogramarComparar UID inicial y actualizado.Guardar el UID y aumentar la versión del evento.

Empieza por el .eml local y después realiza un envío de prueba autorizado con el proveedor real, que puede modificar HTML, enlaces o MIME. Comprueba vista normal, modo oscuro, imágenes bloqueadas, PDF e importación ICS en Gmail, Apple Mail y las versiones de Outlook utilizadas. Para RSVP recorre invitación → respuesta → cambio → cancelación. Registra cliente, versión y resultado en vez de un único «el correo funciona».

Qué elegir para vuestro producto

Caso de usoVía principalLímite de la capacidad
Sitio web con remitente SMS propioSemántica del campo + vinculación al dominio. WebOTP donde sea compatibleNo lee todos los SMS ni accede al correo
Android, con posibilidad de modificar el SMSSMS Retriever APIGoogle Play services, formato del mensaje y hash de la aplicación
Android, sin posibilidad de añadir un hashSMS User Consent API, si el caso cumple sus condicionesConsentimiento para un mensaje, criterios de selección y plazo de espera
Aplicación para iPhoneCampo oneTimeCode y AutoFill del sistemaEl sistema operativo controla el reconocimiento y la sugerencia
Código enviado por correoCorreo claro + campo correcto + sugerencias disponibles del sistemaWebOTP no es una API para leer correos
Asistente para sitios y aplicaciones de tercerosIntegraciones autorizadas de la plataforma que verifiquen el destino y la finalidadProducto independiente con acceso a datos sensibles

La tabla describe vías de integración, no garantías según la marca del teléfono. Por ejemplo, SMS Retriever pertenece a Google Play services: que el dispositivo tenga Android no demuestra que ese mecanismo esté disponible. En dispositivos sin los servicios necesarios, primero hay que comprobar la vía oficialmente compatible con esa plataforma concreta.

Sitio web: primero un campo correcto, después WebOTP

Para un código numérico, utilizad un campo de texto con teclado numérico. type="number" no es adecuado: el código es un identificador, no un número para cálculos. Los ceros iniciales deben conservarse. Las recomendaciones de web.dev para formularios OTP explican la combinación de inputmode y autocomplete="one-time-code".

HTML
<form id="verify-form" action="/auth/verify" method="post">
  <label for="otp">Código del mensaje</label>
  <p id="otp-hint">Introduce 6 cifras. Los ceros iniciales importan.</p>
  <input id="otp" name="code" type="text"
    inputmode="numeric" autocomplete="one-time-code"
    pattern="[0-9]{6}" maxlength="6" required
    aria-describedby="otp-hint otp-status">
  <p id="otp-status" role="status"></p>
  <button type="submit">Confirmar</button>
</form>

Las seis cifras son el contrato explícito de este ejemplo. Los códigos alfanuméricos necesitan otra restricción y otro teclado. La ruta /auth/verify es ilustrativa: el fragmento no incluye la implementación del servidor, la protección de la solicitud ni su vinculación al intento de acceso.

Un único input real suele facilitar el pegado, la edición, AutoFill y los lectores de pantalla más que seis campos independientes. Si el diseño exige seis casillas, siguen siendo necesarios la introducción del código completo, un orden correcto del foco y un nombre accesible. No bloqueéis el pegado ni obliguéis a volver a escribir los dígitos.

WebOTP, según la documentación de Chrome, recibe un SMS con un formato específico y vinculado al dominio. Requiere un contexto seguro y compatibilidad del navegador. Safari puede ofrecer AutoFill del sistema para mensajes adecuados sin implementar la misma API JavaScript. Comprobad la capacidad, no el nombre del sistema operativo.

Text
Código de acceso a Example: 004291

@example.com #004291

La última línea contiene el dominio exacto, sin esquema ni ruta, y el código con el prefijo #. Los marcos incrustados tienen reglas específicas de formato y Permissions Policy que deben consultarse en la documentación de WebOTP. Este ejemplo corresponde a una página normal de nivel superior.

JavaScript
const form = document.querySelector("#verify-form");
const input = document.querySelector("#otp");
const status = document.querySelector("#otp-status");

if (form && input && status && "OTPCredential" in window) {
  const controller = new AbortController();
  const stop = () => controller.abort();
  form.addEventListener("submit", stop, { once: true });
  input.addEventListener("input", stop, { once: true });
  window.addEventListener("pagehide", stop, { once: true });
  const timer = window.setTimeout(stop, 60_000);

  navigator.credentials.get({
    otp: { transport: ["sms"] },
    signal: controller.signal
  }).then(credential => {
    if (!controller.signal.aborted && credential?.code && !input.value) {
      input.value = credential.code;
      input.dispatchEvent(new Event("input", { bubbles: true }));
      status.textContent = "Código introducido. Revísalo y confirma el acceso.";
    }
  }).catch(error => {
    if (error.name !== "AbortError") {
      status.textContent = "Introduce manualmente el código del mensaje.";
    }
  }).finally(() => {
    window.clearTimeout(timer);
    form.removeEventListener("submit", stop);
    input.removeEventListener("input", stop);
    window.removeEventListener("pagehide", stop);
  });
}

La escucha se inicia antes de enviar el SMS esperado. En el flujo real hay que coordinar ese inicio con la solicitud al servidor. El ejemplo cancela la espera al escribir manualmente, enviar el formulario o salir de la página. No sobrescribe un código ya introducido ni envía el formulario automáticamente. Los 60 segundos de espera son un ajuste de la interfaz, no la vigencia del OTP. Si la API no existe, el usuario rechaza la solicitud o se agota el tiempo, sigue disponible el mismo campo manual. En un componente SPA, cancelad también la espera al desmontarlo.

Android: Retriever, User Consent y AutofillService resuelven tareas distintas

Secuencia práctica de Retriever: crear el intento; iniciar la escucha; tras el inicio correcto, solicitar el SMS; enviar código y hash de la aplicación; recibir el resultado; enviar código e intento al servidor. Cada fase puede fallar por separado. Un hash de publicación incorrecto impide que la aplicación recupere el código aunque el SMS llegue al teléfono; la entrega no prueba la integración Retriever.

SMS Retriever API vincula el mensaje a la aplicación mediante un hash. El equipo acuerda el formato del SMS con el servidor, inicia la espera antes del envío y comprueba el mensaje recibido. Así puede implementarse la confirmación sin un permiso general para leer SMS.

Los puntos de entrada del cliente son SmsRetriever.getClient(context).startSmsRetriever() y startSmsUserConsent(senderAddress). La referencia de SmsRetrieverClient describe SMS_RETRIEVED_ACTION, los estados y la protección del receptor mediante SEND_PERMISSION. Iniciar la escucha correctamente no significa que haya llegado un mensaje. El consentimiento se procesa por separado de la entrega.

La integración necesita la dependencia de Google Play services, un receiver correcto y gestión del éxito y del tiempo de espera agotado. El hash debe corresponder al identificador del paquete y al certificado de firma: que funcione una compilación debug no demuestra que funcione la versión de la tienda. Enviad el código recibido a la verificación del servidor para el intento concreto. Recibir un SMS no equivale a iniciar sesión correctamente.

Si no puede añadirse un hash, consultad SMS User Consent API. El usuario autoriza entregar a la aplicación el texto de un único mensaje. Es una ampliación importante de la regla simplificada «un SMS ajeno solo permite una sugerencia del sistema», pero no autoriza recopilar mensajes arbitrarios.

Ejemplo oficial de Google: solicitud del sistema para autorizar la entrega a una aplicación de un SMS con código
Ejemplo de interfaz de la documentación de Google sobre SMS User Consent. El consentimiento corresponde a un mensaje, no a todo el historial de SMS.

En User Consent hay criterios de selección: se espera un código alfanumérico de 4–10 caracteres con al menos un dígito. El remitente no debe estar en los contactos. La documentación describe una ventana de espera de cinco minutos. Son parámetros de funcionamiento de la API, no una longitud ni una vigencia obligatorias para vuestro OTP. Rechazar el consentimiento debe dejar disponible la introducción manual.

AutofillService es el papel de un proveedor independiente de autocompletado, como un gestor de contraseñas que el usuario activa en el sistema. Para una aplicación convencional que recibe su propio código, suele ser otro nivel de tarea. SMS Code Autofill API también corresponde al caso de un proveedor de autocompletado. No autoriza a cualquier aplicación a interceptar SMS.

Leer notificaciones no es una base fiable para un recopilador universal de códigos. En Android 15, el contenido de las notificaciones con un OTP detectado se oculta a los NotificationListenerService no confiables. Que el usuario haya concedido acceso a las notificaciones no elimina esta restricción. No baséis el producto en eludir esa protección.

iPhone: marcad el campo y dejad el reconocimiento al sistema

Los códigos de correo también pueden rellenarse sin notificaciones de aplicaciones de terceros. La guía de funciones de iOS 17 documenta AutoFill desde Mail hacia Safari. Acceder al mismo buzón desde Apple Mail y desde Gmail no implica la misma ruta de reconocimiento. Comprobad el cliente, los ajustes y el campo de destino del correo.

En el listado oficial de funciones de iOS 26 , Apple incluye Verification Code AutoFill from Notifications: los códigos pueden autocompletarse desde notificaciones de aplicaciones. Es una capacidad del sistema, no una API que permita a vuestra aplicación leer las notificaciones de Gmail o de cualquier servicio de mensajería.

En UIKit se utiliza UITextContentType.oneTimeCode. En SwiftUI, el modificador correspondiente del campo:

Swift
TextField("Código de verificación", text: $code)
    .textContentType(.oneTimeCode)
    .keyboardType(.numberPad)

Ese teclado solo es adecuado para códigos numéricos. La sugerencia disponible depende del mensaje reconocido, los ajustes y el estado del dispositivo. Para los SMS de un servicio propio, Apple describe la vinculación al dominio. En una aplicación también cuentan los dominios asociados. Un campo web con autocomplete="one-time-code" y el oneTimeCode nativo expresan la finalidad de la entrada, pero no garantizan una sugerencia desde cualquier origen.

Comprobad por separado los ajustes de notificaciones y vistas previas ocultas. Si el código no aparece en contenido accesible para el sistema, no puede esperarse que la función lo «extraiga» de un buzón cerrado. La aplicación no obtiene permiso para leer las notificaciones de otras aplicaciones. Un TOTP de un gestor de contraseñas es otra fuente independiente y no debe confundirse con un código enviado por correo.

Un asistente universal es un producto independiente

Mejorar vuestro proceso de compra y construir un asistente para cualquier sitio son proyectos de distinta escala. En el segundo caso hay que definir primero dónde funciona: extensión del navegador, proveedor de autocompletado Android seleccionado, cliente de correo o extensión autorizada de la plataforma. Un sitio web no puede convertirse por sí solo en el gestor de códigos del sistema para todo el teléfono.

Gmail API con OAuth puede dar a una aplicación acceso autorizado al contenido de los correos. Pero es acceso a los datos del buzón, no una petición limitada a «dame el código esperado». En la lista de scopes OAuth de Gmail , la lectura del correo pertenece a los restricted scopes. Antes de implementar hay que estudiar los requisitos de verificación de la aplicación y, cuando corresponda, de evaluación de seguridad. Solicitar acceso a todo el buzón para una pantalla OTP propia suele ser desproporcionado.

Otro proveedor de correo requiere su integración compatible y el consentimiento del usuario. No puede prometerse el mismo funcionamiento con cualquier cliente solo porque ambos muestren push. Las plataformas examinadas no ofrecen una interfaz pública universal para «todos los OTP de todos los canales».

Si ese producto está justificado, vinculad el mensaje encontrado a una solicitud concreta: cuenta, dominio exacto o identidad verificada de la aplicación, finalidad de la acción y ventana temporal. No basta con que coincidan el nombre del remitente, el asunto y las últimas seis cifras. Ante una ambigüedad, no adivinéis: mostrad el contexto a la persona o renunciad a la transferencia automática. Confirmar una dirección, iniciar sesión y transferir dinero no pueden agruparse solo porque los códigos tengan el mismo formato.

Qué debe ocurrir después de autocompletar

El usuario pide A, pulsa Reenviar y recibe B. Si la política invalida el anterior, A debe rechazarse aunque llegue tarde y AutoFill lo seleccione primero. Vincula la verificación al intento, destinatario y finalidad; comprueba vencimiento, límite de intentos y uso único. Validar y consumir el código debe ser atómico para evitar que dos solicitudes concurrentes lo acepten dos veces. Autocompletar cambia el campo; el servidor crea la sesión después de verificarlo.

El servidor guarda el estado del intento: para quién, para qué y cuándo se emitió el código, cuándo caduca, cuántas comprobaciones se han hecho y si ya se utilizó. La verificación debe considerar ese contexto, limitar los intentos de adivinación y los reenvíos, e invalidar atómicamente el código tras usarlo correctamente. Definid de antemano qué ocurre con el código anterior después de un reenvío y reflejadlo en la interfaz. Un temporizador en pantalla no sustituye la caducidad del servidor.

No registréis OTP ni contenido de correos o SMS en analítica, consola o mensajes de error. Podéis medir intentos, demora de entrega, frecuencia de reenvío y resultado de la verificación sin guardar los secretos. Distinguid «código sugerido», «campo rellenado» y «acción confirmada por el servidor»: son eventos diferentes, no un único indicador de acceso correcto.

La interfaz debe conservar lo introducido ante un fallo temporal de red, explicar la caducidad, permitir corregir la dirección o el número y reenviar tras un límite comprensible. No vaciéis el campo con cada fallo ni mostréis «código incorrecto» si la solicitud ni siquiera llegó al servidor. El autocompletado no debe impedir el pegado manual ni cambiar inesperadamente los dígitos ya escritos.

Pruebas antes de publicar

SituaciónResultado esperado
El código empieza por cerosLos ceros se conservan al escribir, pegar y enviar
El mensaje llega antes de iniciar la esperaEl usuario puede introducir el código. La interfaz no se bloquea
Otro dominio, cuenta o finalidadLa coincidencia de los dígitos no basta para transferirlo automáticamente
El usuario deniega el accesoEl mismo recorrido puede completarse manualmente
Reenvío y código anteriorSe aplica la política explícita del servidor
Entrada manual durante la esperaUn AutoFill tardío no sobrescribe lo introducido
Fallo de red, caducidad y reutilizaciónEstados distintos y comprensibles, con verificación correcta del servidor
Teclado, lector de pantalla y texto ampliadoEl campo tiene nombre, los errores están asociados y el foco no salta
Firma de publicación Android y dispositivos objetivoSe comprueba la integración real, no solo una compilación debug

La matriz debe cubrir canales e implementaciones: SMS del servicio propio, correo, navegador compatible con WebOTP, Safari, dispositivos Android objetivo con los servicios necesarios e iPhone con una versión adecuada del sistema. Probad por separado varios intentos simultáneos, cambios de cuenta, salida de la página y ausencia de notificación. «Funciona en iOS» no sustituye registrar la versión, los ajustes y el caso probado.

Un skill para desarrollar correos electrónicos

A partir de esta investigación, creamos un skill Email Development para Codex y Claude Code. Ayuda a crear y mejorar correos, desde el asunto y la alternativa de texto plano hasta las plantillas HTML, los mensajes OTP, los datos estructurados de Gmail y la verificación en clientes de correo.

El skill examina las plantillas, los datos y el proveedor de envío existentes. Para los códigos de verificación tiene en cuenta la claridad del mensaje, la caducidad, los ceros iniciales, el intento de acceso y los límites reales de AutoFill. Para pedidos y reservas ayuda a elegir el marcado compatible y comprobar los requisitos de Gmail. No promete forzar la aparición de Copy code ni obtener acceso al buzón de otra persona.

Instalación en Codex:

Codex
$skill-installer install https://github.com/wladislaw353/agent-skills/tree/main/skills/email-development

Invocadlo con $email-development. La guía de instalación para Claude Code explica cómo instalar y actualizar la colección. Con el plugin, usad /agent-skills:email-development. Con una instalación manual en ~/.claude/skills/, usad /email-development.

Ejemplo de solicitud: «Analiza nuestros correos de verificación. Mejora el HTML y la versión de texto plano, comprueba la accesibilidad, la compatibilidad y las funciones de Gmail, y prepara el resultado para revisión». El skill ayuda con el análisis y la implementación. El envío de correos y los cambios en la configuración del dominio requieren una instrucción aparte.

El skill ampliado también incluye una comprobación de compatibilidad de etiquetas y CSS, validación de adjuntos MIME, las diferencias entre el logotipo del mensaje, Promotions y BIMI, generación segura de JSON-LD y el ciclo de vida de las invitaciones event.ics. Las comprobaciones distinguen los resultados validados de las funciones que aún necesitan una prueba en un cliente de correo real.