Cómo funcionan los formularios

Un formulario guarda dos copias de lo que ven los visitantes. document es el borrador que editas, y publishedDocument es lo que usan la página alojada, la inserción y el endpoint de suscripción. Guardar solo cambia el borrador, y POST /forms/{id}/publish lo copia a la versión activa. hasUnpublishedChanges te indica que las dos difieren.

• —draft: nunca publicado. Nadie puede verlo ni suscribirse a través de él.
• —live: publicado y aceptando suscripciones.
• —paused: publicado pero cerrado. La página muestra el mensaje de cierre de los textos del formulario y las suscripciones se rechazan.

Los settings son otra cosa: adónde van las suscripciones, el doble opt-in, el remitente, lo que pasa tras la suscripción y a quién se avisa de cada suscripción. Se aplican en cuanto se guardan, estén publicados o no.

Un documento es una lista de fields, los textos de copy que los rodean y un style. Cada campo de entrada tiene una key, el nombre con el que se envía su respuesta: una letra minúscula seguida de hasta 39 letras minúsculas, dígitos o guiones bajos, única en el formulario y que nunca empieza por oe_. Todo formulario tiene exactamente un campo email, con la clave email y obligatorio.

• —Campos de entrada: email, text, textarea, number, phone, url y date.
• —Campos de elección: select, radio y checkboxes, cada uno con options.
• —checkbox para un sí o un no, y consent para una casilla que hay que marcar cuando es obligatoria.
• —audiences deja que la persona elija listas: cada value de opción es un id de audiencia de este espacio de trabajo.
• —hidden lleva un valor que el visitante nunca ve: el que envía tu página o, si no, su defaultValue, como el nombre de una campaña.
• —heading, paragraph y divider solo sirven para maquetar el formulario y no envían nada.

Pon mapsTo en firstName, lastName o name en un campo de texto, y la respuesta pasa a ser el nombre del contacto que crea la suscripción. Un contacto que ya existe conserva su nombre. Cada respuesta se guarda en el envío con la etiqueta que tenía, así que los envíos antiguos se siguen leyendo bien después de que cambie el formulario.

Publica primero. Después usa la de las tres opciones que mejor encaje con la página. Todas llegan al mismo formulario y cuentan las mismas suscripciones. Las vistas solo se cuentan en la página alojada y en la inserción, así que las suscripciones a través de tu propio HTML o código suben la tasa de conversión.

• —La página alojada en url, una página propia que puedes enlazar desde cualquier sitio.
• —El script de inserción, que pone el formulario en tu página dentro de un marco que ajusta solo su tamaño.
• —Tu propio HTML o código, que envía las respuestas a subscribeUrl.

<script src="https://openemail.uk/embed/form.js" data-openemail-form="frm_3b9d2e7a1c4f80d56e2a9b14" async></script>

<form action="https://api.openemail.uk/subscribe/frm_3b9d2e7a1c4f80d56e2a9b14" method="post">  <input type="email" name="email" required>  <div style="position:absolute;left:-9999px" aria-hidden="true">    <input type="text" name="oe_website" tabindex="-1" autocomplete="off">  </div>  <button type="submit">Subscribe</button></form>

Un formulario HTML simple se redirige a la página de agradecimiento, o a settings.redirectUrl. El código que envía JSON recibe en su lugar una respuesta JSON, descrita en la página del endpoint de suscripción.

Con settings.doubleOptIn activado, una suscripción se guarda como pending y la persona recibe por correo un enlace desde settings.senderAddress, una dirección de este espacio de trabajo. Se une a las audiencias cuando lo abre. El enlace funciona durante siete días. Una persona que antes se dio de baja de una audiencia solo vuelve a quedar suscrita de esta forma, nunca mediante un formulario con opt-in simple. Suscribirse de nuevo antes de confirmar actualiza la suscripción pendiente en lugar de añadir otra.

Para proteger a las personas a las que escribes, una dirección recibe como máximo una confirmación por formulario cada diez minutos y cinco al día en todo el espacio de trabajo. Puedes aprobar tú mismo una suscripción pendiente o enviarle un enlace nuevo.

• —Leer requiere forms:read y cambiar requiere forms:write. Aprobar una suscripción también requiere contacts:write, porque añade un contacto.
• —Todo lo que haga que un formulario envíe correo también requiere emails:send: activar el doble opt-in, configurar el remitente o el correo de confirmación, publicar o reanudar un formulario con doble opt-in, y reenviar una confirmación.
• —Una clave de API y el propietario ven todos los formularios del espacio de trabajo. Una app que conectó un miembro solo ve los formularios que creó ese miembro, y solo las audiencias que creó ese miembro más las integradas.
• —Si se crea, actualiza, publica, reanuda o duplica un formulario cuyo remitente o direcciones de aviso quedan fuera de lo que puede alcanzar una clave o una app limitada, la respuesta es 422 capability_unsupported.
• —Una clave o una app limitada a algunas direcciones solo puede poner como remitente y como direcciones de aviso direcciones que tenga.
• —Eliminar un formulario pide a una app OAuth un código de verificación, como otros cambios destructivos. Una clave de API nunca lo necesita.

Los webhooks form.submitted y form.confirmed avisan a tus sistemas de cada suscripción. Un webhook limitado a algunas direcciones nunca los recibe, porque las suscripciones pertenecen a todo el espacio de trabajo.

• —Un campo llamado oe_website es una trampa para bots: déjalo vacío y fuera de la pantalla, como hace el HTML de arriba. Una suscripción que lo rellena recibe una respuesta normal y se descarta.
• —La página alojada y la inserción también comprueban una hora de inicio firmada, y un formulario devuelto más rápido de lo que una persona podría rellenarlo se descarta del mismo modo.
• —Una misma red puede enviar 40 suscripciones en diez minutos, en el conjunto de tus formularios y sea cual sea el resultado. A partir de ahí, las llamadas con JSON reciben 429 form_rate_limited, y un formulario HTML simple se redirige a la página alojada con ?outcome=limited.
• —Un espacio de trabajo admite 100 formularios por defecto.

Todo lo de aquí está también en el SDK como openemail.forms y en la CLI como openemail forms, y el servidor MCP tiene herramientas de formularios, así que un agente puede crear, publicar y seguir un formulario. Por MCP, el cliente escribe el diseño por sí mismo y lo pasa como document.

Enviar datos por POST a subscribeUrl desde tu propio código no requiere ninguna credencial. Envía las respuestas como JSON, añade la página en la que estaba el formulario como oe_source, omite oe_started y envía oe_website vacío o no lo envíes. Todas las suscripciones desde una misma red comparten el límite de 40 cada diez minutos, así que un servidor que reenvía suscripciones de muchas personas lo alcanza enseguida: en su lugar, añade a las personas que ya conoces con la importación a una audiencia.