Formularios web: ejemplo con Next.js

Integra un formulario de suscripción en Next.js con una ruta BFF: el navegador envía a tu aplicación; tu ruta llama a Mailoo con credenciales del servidor. Prefiere @mailoo/forms. Para el contrato de la API, consulta website-forms{.interpreted-text role="doc"}.

Requisitos previos

• Un proyecto de Mailoo con una integración de tipo Form (FORM)
• Una clave API con webhook.form-submission (o FULL)

Entorno (solo servidor)

@mailoo/forms usa por defecto el prefijo de entorno MAILOO_CONTACT_FORM_INTEGRATION para integraciones FORM. El nombre es histórico: no es la integración CONTACT_FORM (comentarios). Los comentarios usan MAILOO_FEEDBACK_INTEGRATION --- consulta feedback-form-nextjs-example{.interpreted-text role="doc"}.

Añade a .env.local (o tus secretos del host):

MAILOO_CONTACT_FORM_INTEGRATION_API=https://api.mailoo.app
MAILOO_CONTACT_FORM_INTEGRATION_API_KEY=your-api-key-here
MAILOO_CONTACT_FORM_INTEGRATION_PROJECT_UID=your-project-uid-here
MAILOO_CONTACT_FORM_INTEGRATION_ID=your-form-integration-id-here

Las cuatro son obligatorias para el prefijo por defecto. No uses NEXT_PUBLIC_* para la URL de la API ni la clave. Para una segunda integración FORM, pasa un prefix personalizado (o getConfig) a la fábrica de rutas.

Controlador de ruta BFF

// app/api/v1/webhooks/forms/submit/route.ts
import { createFormSubmitHandler } from '@mailoo/forms/routes'

export const POST = createFormSubmitHandler()

Formulario del cliente

Envía a tu BFF. Campos del cuerpo para FORM: email (obligatorio), name, subject, content, source, metadata opcionales. Usa content (no message) si quieres un cuerpo personalizado en el buzón.

Con el hook del paquete:

'use client'

import { useMailooFormSubmit } from '@mailoo/forms/hooks'

export function NewsletterForm() {
  const { submit, loading, error } = useMailooFormSubmit({
    endpoint: '/api/v1/webhooks/forms/submit',
  })

  async function onSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault()
    const fd = new FormData(e.currentTarget)
    await submit({
      email: String(fd.get('email') || '').trim(),
      name: String(fd.get('name') || '').trim() || undefined,
      source: typeof window !== 'undefined' ? window.location.href : '',
    })
  }

  return (
    <form onSubmit={onSubmit}>
      <input name="name" placeholder="Your name (optional)" disabled={loading} />
      <input name="email" type="email" required disabled={loading} />
      <button type="submit" disabled={loading}>
        {loading ? 'Subscribing…' : 'Subscribe'}
      </button>
      {error ? <p>{error}</p> : null}
    </form>
  )
}

O llama a fetch tú mismo con la misma estructura JSON.

Relacionado

• website-forms{.interpreted-text role="doc"} --- endpoint y comportamiento de suscriptores
• feedback-form-nextjs-example{.interpreted-text role="doc"} --- CONTACT_FORM / comentarios
• nextjs-packages{.interpreted-text role="doc"} --- resumen de paquetes