Формы
`forms.list`, `get`, `create`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `list_starters`, `get_starter`, `list_submissions`, `get_submission`, `delete_submission`, `delete_submissions`, `approve_submission`, `resend_confirmation` и `subscribe`.
Все методы
form = client.forms.create( name: "Newsletter sign-up", starter: "newsletter", settings: {audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"]}, publish: true) puts form[:url], form[:subscribeUrl] saved = client.forms.update( form[:id], settings: {doubleOptIn: true, senderAddress: "[email protected]"}, expectedUpdatedAt: form[:updatedAt]) signup = client.forms.subscribe(form[:id], email: "[email protected]", first_name: "Ann", consent: true) client.forms.iterate_submissions(form[:id], status: "pending") do |submission| client.forms.resend_confirmation(form[:id], submission[:id]) if submission[:expired]end stats = client.forms.analytics(form[:id], days: 30)starters = client.forms.list_starters client.forms.pause(form[:id])client.forms.resume(form[:id])copy = client.forms.duplicate(form[:id])client.forms.delete(copy[:id]) puts saved[:senderIssue], signup[:outcome], stats.dig(:totals, :conversion), starters.sizeФорма хранит черновик document и publishedDocument, который видят посетители. update меняет черновик и настройки, а publish публикует черновик. Настройки вступают в силу сразу, опубликована форма или нет, а expectedUpdatedAt отклоняет сохранение, которое перезаписало бы чужое, с 409 version_conflict, выбрасываемым как OpenEmail::ConflictError.
Поля формы сохраняют имена API в camelCase (expectedUpdatedAt:, doubleOptIn) и передаются именованными аргументами или одним Hash, тогда как фильтры и параметры являются именованными аргументами в snake_case (status: в list_submissions, offset_minutes: в analytics). Форма возвращается как Hash с ключами типа Symbol, поэтому form[:subscribeUrl] читает адрес, который принимает подписки.
Для чтения нужна forms:read, а для изменения forms:write. approve_submission нужна также contacts:write, потому что он добавляет контакт. resend_confirmation нужна также emails:send, как и вызову, который заставляет форму отправлять почту: включению doubleOptIn, заданию senderAddress или письма с подтверждением, публикации или возобновлению формы с двойным подтверждением. delete запрашивает у токена доступа OAuth код подтверждения, а у API-ключа никогда. Пока у токена нет подтверждения, delete выбрасывает OpenEmail::PermissionError с step_up_required?, равным true.
subscribe подписывает человека так же, как страница формы, и не отправляет учётных данных, даже из клиента, у которого они есть, поэтому api_key: игнорируется. Ответы передаются именованными аргументами или одним Hash с ключами полей формы. Все подписки из одной сети делят общий лимит в 40 за десять минут, поэтому сервер, пересылающий подписки многих людей, быстро его исчерпает: людей, которых вы уже знаете, добавляйте через audiences.import_contacts. Сверх лимита вызов выбрасывает OpenEmail::RateLimitError. Передайте страницу, на которой была форма, как oe_source:, не передавайте oe_started, а oe_website отправляйте пустым или не отправляйте вовсе.
422 от subscribe означает invalid_form_submission, выбрасываемый как OpenEmail::ValidationError, а fields ошибки перечисляет каждый отсутствующий или некорректный ответ как Hash с key и error, с причинами вроде required, email и option. OpenEmail::FORM_FIELD_ERRORS перечисляет все причины. Гем работает на сервере. Браузер сам отправляет ответы на subscribeUrl формы, телом JSON или с заголовком Accept: application/json, и получает JSON в ответ с любого источника. Без того и другого он получает перенаправление 303 на размещённую страницу.
Ответ: форма
list возвращает одну OpenEmail::Page форм, сначала новые, без document и settings, а list_all и iterate обходят все страницы. get, create, update, publish, pause, resume и duplicate возвращают всю форму как Hash, в котором добавлены document, publishedDocument, settings, audiences, senderIssue и senderProblem.
idString- Постоянный идентификатор: `frm_` и 24 шестнадцатеричных символа.
statusString- `draft` до первой публикации, затем `live`, пока форма принимает подписки, и `paused`, пока не принимает. Форма никогда не возвращается в `draft`. `OpenEmail::FORM_STATUSES` перечисляет все три.
urlString- Размещённая у нас страница опубликованной формы, чтобы делиться ею как ссылкой.
subscribeUrlString- Куда обычная HTML-форма или скрипт в браузере отправляет ответы.
documentHash- Черновик: `fields` по порядку, окружающие их тексты `copy` и оформление `style`.
publishedDocumentHash or nil- То, что посетители видят сейчас, или nil до первой публикации.
settingsHash- Куда попадают подписки и что происходит после подписки: `audienceIds`, `doubleOptIn`, `senderAddress`, письмо с подтверждением, `successAction`, `redirectUrl` и `notifyAddresses`.
hasUnpublishedChangesBoolean- True, когда черновик отличается от того, что видят посетители. Всегда false до первой публикации.
senderIssueString or nil- Почему форма с двойным подтверждением сейчас не может отправлять письма с подтверждением: `missing`, `not_sendable` или `not_allowed`. nil, когда может. `OpenEmail::FORM_SENDER_ISSUES` перечисляет все три.
statsHash- `views`, `submissions`, `added`, `pending` и `lastSubmittedAt`, подсчитанные в момент чтения.
Заявки
list_submissions выдаёт страницы от новых к старым, с q: для поиска по адресам электронной почты и status: для pending или added, а list_all_submissions и iterate_submissions обходят все страницы. OpenEmail::FORM_SUBMISSION_STATUSES перечисляет оба статуса. Каждая заявка является Hash, который хранит ответы в том виде, в каком они были отправлены, вместе с подписями полей, поэтому читается правильно и после изменения формы.
resend_confirmation возвращает заявку с confirmationSent. Оно равно false, если ничего не ушло: один адрес получает одно подтверждение на форму раз в десять минут и пять в день по всему рабочему пространству, а уже добавленная заявка не получает ни одного. expired отмечает ожидающую подписку, последняя ссылка которой истекла.