React (@frontmail/react)

npm install @frontmail/react

Funciona con React 18 y 19, incluido Next.js (úsalo en componentes de cliente).

Provider

Envuelve tu app (o solo la parte con formularios) en FrontmailProvider. Mantén estable el objeto de opciones: defínelo a nivel de módulo o con useMemo:

import { FrontmailProvider } from '@frontmail/react';

const frontmailOptions = { publicKey: 'pk_4f2a…', blockHeadless: true };

export function App() {
  return (
    <FrontmailProvider options={frontmailOptions}>
      <Routes />
    </FrontmailProvider>
  );
}

options acepta todo lo que acepta init(). También puedes pasar un cliente existente: <FrontmailProvider client={client}>.

FrontmailForm

La forma más rápida de tener un formulario funcionando: envía mediante sendForm, renderiza Turnstile cuando le pasas una site key y expone el estado del envío:

import { FrontmailForm } from '@frontmail/react';

export function ContactForm() {
  return (
    <FrontmailForm
      serviceId="svc_01J9…"
      templateId="tpl_contact"
      turnstileSiteKey="YOUR_TURNSTILE_SITE_KEY"
      onSuccess={(result) => console.log(result.status)}
      onError={(error) => console.error(error.code)}
    >
      {({ status, error }) => (
        <>
          <input name="name" required />
          <input name="email" type="email" required />
          <textarea name="message" required />
          <button disabled={status === 'sending'}>Enviar</button>
          {status === 'sent' && <p>¡Gracias!</p>}
          {status === 'held' && <p>Recibido: lo entregaremos en breve.</p>}
          {error && <p role="alert">{error.message}</p>}
        </>
      )}
    </FrontmailForm>
  );
}

Props: serviceId, templateId, turnstileSiteKey, turnstileOptions, locale, sendOptions, resetOnSuccess (por defecto true), onSuccess, onError y cualquier atributo de <form>. Los hijos pueden ser nodos o una función del estado { status, error, result }.

locale (p. ej. "de") envía el correo en ese idioma de la plantilla (como campo de formulario fm_locale; un campo fm_locale dentro del formulario tiene prioridad). result.locale es el idioma usado.

turnstileSiteKey es la site key de tu propio widget de Turnstile (Seguridad → Protección contra bots (Turnstile) en el panel): consulta Cloudflare Turnstile. Omítela si la plantilla no exige CAPTCHA.

useSendEmail

Para interfaces personalizadas y formularios controlados:

import { useState } from 'react';
import { useSendEmail } from '@frontmail/react';

function Newsletter() {
  const { send, status, error, reset } = useSendEmail('svc_01J9…', 'tpl_newsletter');
  const [email, setEmail] = useState('');

  return (
    <form onSubmit={async (e) => { e.preventDefault(); await send({ email }); }}>
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
      <button disabled={status === 'sending'}>Suscribirme</button>
      {status === 'error' && <p role="alert">{error?.message}</p>}
    </form>
  );
}

status pasa de idle → sending → sent | held | error. send() y sendForm() se resuelven con el resultado, o con undefined si hay un error (el error queda en error), así que no necesitas try/catch. Ambos aceptan opciones como segundo argumento, p. ej. send({ email }, { locale: 'de' }).

useFrontmail

Devuelve el cliente del provider para todo lo demás, p. ej. getStatus:

import { useFrontmail } from '@frontmail/react';

const client = useFrontmail();
const status = await client.getStatus(messageId, { token });

Parámetros tipados

Con los tipos generados, useSendEmail('svc_…', 'tpl_contact').send({...}) comprueba los tipos de los parámetros de esa plantilla.

Proyecto de ejemplo: examples/react.