Формы на сайте: пример для Next.js

Обновлено: Aug 31, 2026Раздел: Интеграции

Интегрируйте форму подписки в Next.js с BFF-маршрутом: браузер отправляет данные в ваше приложение, а ваш маршрут вызывает Mailoo с серверными учётными данными. Предпочтительнее использовать @mailoo/forms. Контракт API описан в website-forms{.interpreted-text role="doc"}.

Предварительные требования

  • Проект Mailoo с интеграцией Form (FORM)
  • API-ключ с webhook.form-submission (или FULL)

Окружение (только сервер)

@mailoo/forms по умолчанию использует префикс переменных окружения MAILOO_CONTACT_FORM_INTEGRATION для интеграций FORM. Название историческое: это не интеграция CONTACT_FORM (обратная связь). Обратная связь использует MAILOO_FEEDBACK_INTEGRATION --- см. feedback-form-nextjs-example{.interpreted-text role="doc"}.

Добавьте в .env.local (или в секреты хоста):

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

Все четыре переменные обязательны для префикса по умолчанию. Не используйте NEXT_PUBLIC_* для URL API или ключа. Для второй интеграции FORM передайте пользовательский prefix (или getConfig) в фабрику маршрутов.

Обработчик BFF-маршрута

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

export const POST = createFormSubmitHandler()

Клиентская форма

Отправляйте данные в ваш BFF. Поля тела для FORM: email (обязательно), необязательные name, subject, content, source, metadata. Используйте content (а не message), если вы хотите задать произвольное тело входящего сообщения.

С хуком пакета:

'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>
  )
}

Или выполните fetch самостоятельно с тем же форматом JSON.

Связанные страницы

  • website-forms{.interpreted-text role="doc"} --- эндпоинт и поведение подписчиков
  • feedback-form-nextjs-example{.interpreted-text role="doc"} --- CONTACT_FORM / обратная связь
  • nextjs-packages{.interpreted-text role="doc"} --- обзор пакетов
📚