Как работают формы

Форма хранит две копии того, что видят посетители. document это черновик, который вы редактируете, а publishedDocument это то, что используют размещённая у нас страница, встроенная форма и эндпоинт подписки. Сохранение меняет только черновик, а POST /forms/{id}/publish копирует его в опубликованную версию. hasUnpublishedChanges сообщает, что эти две копии различаются.

• —draft: ни разу не публиковалась. Никто не может её увидеть или подписаться через неё.
• —live: опубликована и принимает подписки.
• —paused: опубликована, но закрыта. Страница показывает сообщение о закрытии из её текстов, а подписки отклоняются.

С settings всё иначе: куда попадают подписки, двойное подтверждение, отправитель, что происходит после подписки и кому сообщают о каждой подписке. Они действуют сразу после сохранения, опубликована форма или нет.

Документ состоит из списка fields, окружающих их текстов copy и оформления style. У каждого поля ввода есть key, имя, под которым отправляется его ответ: строчная буква, за которой следуют до 39 строчных букв, цифр или подчёркиваний, уникальное в пределах формы и никогда не начинающееся с oe_. В каждой форме ровно одно поле email, его ключ email, и оно обязательное.

• —Поля ввода: email, text, textarea, number, phone, url и date.
• —Варианты выбора: select, radio и checkboxes, у каждого есть options.
• —checkbox для ответа «да» или «нет», и consent для флажка, который нужно отметить, если он обязательный.
• —audiences позволяет человеку выбрать списки: каждое значение value варианта является id аудитории в этом рабочем пространстве.
• —hidden несёт значение, которого посетитель никогда не видит: то, которое отправляет ваша страница, а иначе его defaultValue, например название кампании.
• —heading, paragraph и divider только размечают форму и ничего не отправляют.

Задайте текстовому полю mapsTo со значением firstName, lastName или name, и ответ станет именем контакта, которого создаёт подписка. Уже существующий контакт сохраняет своё имя. Каждый ответ хранится в заявке вместе с подписью, которая у него была, поэтому старые заявки читаются правильно и после изменения формы.

Сначала опубликуйте форму. Затем используйте тот из трёх вариантов, который подходит странице. Все они ведут к одной и той же форме и учитывают одни и те же подписки. Просмотры считаются только на размещённой у нас странице и во встроенной форме, поэтому подписки через ваш собственный HTML или код повышают коэффициент конверсии.

• —Размещённая у нас страница по адресу url: отдельная страница, на которую можно дать ссылку откуда угодно.
• —Скрипт встраивания, который ставит форму на вашу страницу во фрейме, сам подбирающем свой размер.
• —Ваш собственный HTML или код, отправляющий ответы на 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>

Обычная HTML-форма перенаправляется на страницу благодарности или на settings.redirectUrl. Код, который отправляет JSON, вместо этого получает ответ в JSON, описанный на странице о подписке.

Когда settings.doubleOptIn включён, подписка сохраняется как pending, а человеку приходит письмо со ссылкой с адреса settings.senderAddress, одного из адресов этого рабочего пространства. Он вступает в аудитории, когда открывает её. Ссылка действует семь дней. Человек, который ранее отписался от аудитории, подписывается снова только так и никогда через форму без двойного подтверждения. Повторная подписка до подтверждения обновляет ожидающую подписку, а не добавляет новую.

Чтобы защитить людей, которым вы пишете, один адрес получает не больше одного подтверждения на форму раз в десять минут и не больше пяти в день по всему рабочему пространству. Вы можете сами одобрить ожидающую подписку или отправить ей новую ссылку.

• —Для чтения нужен forms:read, а для изменения нужен forms:write. Для одобрения подписки нужен также contacts:write, потому что оно добавляет контакт.
• —Для всего, что заставляет форму отправлять почту, нужен также emails:send: для включения двойного подтверждения, задания отправителя или письма с подтверждением, публикации или возобновления формы с двойным подтверждением и повторной отправки подтверждения.
• —API-ключ и владелец видят все формы рабочего пространства. Приложение, подключённое участником, видит только формы, созданные этим участником, и только аудитории, созданные этим участником, а также встроенные.
• —Создание, обновление, публикация, возобновление или дублирование формы, у которой отправитель или адреса для уведомлений выходят за пределы того, что доступно ограниченному ключу или приложению, даёт 422 capability_unsupported.
• —Ключ или приложение, ограниченные некоторыми адресами, могут указать в качестве отправителя и адресов для уведомлений только те адреса, которые у них есть.
• —Удаление формы требует от приложения OAuth код подтверждения, как и другие разрушительные изменения. API-ключу он никогда не нужен.

Вебхуки form.submitted и form.confirmed сообщают вашим системам о каждой подписке. Вебхук, ограниченный некоторыми адресами, никогда их не получает, потому что подписки принадлежат всему рабочему пространству.

• —Поле с именем oe_website служит ловушкой для ботов: оставляйте его пустым и за пределами экрана, как это делает HTML выше. Подписка, которая его заполняет, получает обычный ответ и отбрасывается.
• —Размещённая у нас страница и встроенная форма также проверяют подписанное время начала, и форма, отправленная обратно быстрее, чем человек успел бы её заполнить, отбрасывается так же.
• —Из одной сети можно отправить 40 подписок за десять минут, по всем вашим формам вместе и независимо от результата. После этого код, который отправляет JSON, получает 429 form_rate_limited, а обычная HTML-форма переходит на размещённую у нас страницу с ?outcome=limited.
• —По умолчанию рабочее пространство вмещает 100 форм.

Всё описанное здесь есть также в SDK как openemail.forms и в CLI как openemail forms, а у MCP-сервера есть инструменты для форм, поэтому агент может создать форму, опубликовать её и следить за ней. Через MCP клиент сам пишет дизайн и передаёт его как document.

Для отправки на subscribeUrl из собственного кода учётные данные не нужны. Отправляйте ответы в JSON, добавьте страницу, на которой была форма, как oe_source, не указывайте oe_started, а oe_website отправляйте пустым или не отправляйте вовсе. Все подписки из одной сети делят один лимит в 40 подписок на каждые десять минут, поэтому сервер, который передаёт подписки многих людей, быстро его исчерпает: людей, которых вы уже знаете, лучше добавляйте импортом в аудиторию.