Формы
`forms->list`, `listAll`, `iterate`, `get`, `create`, `design`, `redesign`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `listStarters`, `getStarter`, `listSubmissions`, `getSubmission`, `deleteSubmission`, `deleteSubmissions`, `approveSubmission`, `resendConfirmation` и `subscribe`.
Все методы
use OpenEmail\Constants\FormStarterSlugs;use OpenEmail\Constants\FormSubmissionStatuses; $form = $client->forms->create([ 'name' => 'Newsletter sign-up', 'starter' => FormStarterSlugs::NEWSLETTER, 'settings' => ['audienceIds' => ['aud_4c1b8e2a7d9f05c36b4e8a71']], 'publish' => true,]); echo $form['url'], ' ', $form['subscribeUrl'], PHP_EOL; $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,]); foreach ($client->forms->iterateSubmissions($form['id'], status: FormSubmissionStatuses::PENDING) as $submission) { if ($submission['expired']) { $client->forms->resendConfirmation($form['id'], $submission['id']); }} $stats = $client->forms->analytics($form['id'], days: 30);$starters = $client->forms->listStarters(); $client->forms->pause($form['id']);$client->forms->resume($form['id']);$copy = $client->forms->duplicate($form['id']);$client->forms->delete($copy['id']); echo $saved['senderIssue'] ?? 'ready to send', ' ', $signup['outcome'], ' ', $stats['totals']['conversion'] ?? 'no views yet', ' ', count($starters), PHP_EOL;Форма хранит черновик document и publishedDocument, который видят посетители. update меняет черновик и настройки, а publish публикует черновик. Настройки вступают в силу сразу, опубликована форма или нет, а expectedUpdatedAt отклоняет сохранение, которое перезаписало бы чужое, с 409 version_conflict, выбрасываемым как ConflictException.
Поля формы являются ключами одного массива с именами API в camelCase (expectedUpdatedAt, doubleOptIn), тогда как фильтры и параметры являются именованными аргументами (status: в listSubmissions, offsetMinutes: в analytics). Форма возвращается как массив с ключами в camelCase, поэтому $form['subscribeUrl'] читает адрес, который принимает подписки.
design создаёт новую форму-черновик по письменному описанию, как «Создать с ИИ» на странице «Формы», а redesign применяет письменные указания к черновику формы, как «Спросить ИИ» в конструкторе форм. Каждый тратит одно действие ИИ и записывает только черновик, поэтому посетители не увидят ничего нового до publish.
Для чтения нужна forms:read, а для изменения forms:write. approveSubmission нужна также contacts:write, потому что он добавляет контакт. resendConfirmation нужна также emails:send, как и вызову, который заставляет форму отправлять почту: включению doubleOptIn, заданию senderAddress или письма с подтверждением, публикации или возобновлению формы с двойным подтверждением. delete запрашивает у токена доступа OAuth код подтверждения, а у API-ключа никогда. Пока у токена нет подтверждения, delete выбрасывает PermissionException, у которого isStepUpRequired() равно true.
subscribe подписывает человека так же, как страница формы, и не отправляет учётных данных, даже из клиента, у которого они есть, поэтому apiKey: игнорируется. Ответы передаются вторым аргументом, одним массивом с ключами полей формы. Все подписки из одной сети делят общий лимит в 40 за десять минут, поэтому сервер, пересылающий подписки многих людей, быстро его исчерпает: людей, которых вы уже знаете, добавляйте через audiences->importContacts. Сверх лимита вызов выбрасывает RateLimitException. Передайте страницу, на которой была форма, как oe_source, не передавайте oe_started, а oe_website отправляйте пустым или не отправляйте вовсе.
422 от subscribe означает invalid_form_submission, выбрасываемый как ValidationException, а fields исключения перечисляет каждый отсутствующий или некорректный ответ как массив с key и error, с причинами вроде required, email и option. OpenEmail\Constants\FormFieldErrors перечисляет все причины. Пакет работает на сервере. Браузер сам отправляет ответы на subscribeUrl формы, телом JSON или с заголовком Accept: application/json, и получает JSON в ответ с любого источника. Без того и другого он получает перенаправление 303 на размещённую страницу.
Ответ: форма
list возвращает одну OpenEmail\Result\Page форм, сначала новые, без document и settings. listAll возвращает все формы одним массивом, а iterate возвращает Generator, который обходит все страницы по одной форме. get, create, update, publish, pause, resume и duplicate возвращают всю форму как массив, в котором добавлены document, publishedDocument, settings, audiences, senderIssue и senderProblem.
idstring- Постоянный идентификатор: `frm_` и 24 шестнадцатеричных символа.
statusstring- `draft` до первой публикации, затем `live`, пока форма принимает подписки, и `paused`, пока не принимает. Форма никогда не возвращается в `draft`. `OpenEmail\Constants\FormStatuses` перечисляет все три.
urlstring- Размещённая у нас страница опубликованной формы, чтобы делиться ею как ссылкой.
subscribeUrlstring- Куда обычная HTML-форма или скрипт в браузере отправляет ответы.
documentarray- Черновик: `fields` по порядку, окружающие их тексты `copy` и оформление `style`.
publishedDocumentarray or null- То, что посетители видят сейчас, или null до первой публикации.
settingsarray- Куда попадают подписки и что происходит после подписки: `audienceIds`, `doubleOptIn`, `senderAddress`, письмо с подтверждением, `successAction`, `redirectUrl` и `notifyAddresses`.
hasUnpublishedChangesbool- True, когда черновик отличается от того, что видят посетители. Всегда false до первой публикации.
senderIssuestring or null- Почему форма с двойным подтверждением сейчас не может отправлять письма с подтверждением: `missing`, `not_sendable` или `not_allowed`. null, когда может. `OpenEmail\Constants\FormSenderIssues` перечисляет все три.
statsarray- `views`, `submissions`, `added`, `pending` и `lastSubmittedAt`, подсчитанные в момент чтения.
Заявки
listSubmissions выдаёт страницы от новых к старым, с q: для поиска по адресам электронной почты и status: для pending или added, а listAllSubmissions и iterateSubmissions обходят все страницы. OpenEmail\Constants\FormSubmissionStatuses перечисляет оба статуса. Каждая заявка является массивом, который хранит ответы в том виде, в каком они были отправлены, вместе с подписями полей, поэтому читается правильно и после изменения формы.
resendConfirmation возвращает заявку с confirmationSent. Оно равно false, если ничего не ушло: один адрес получает одно подтверждение на форму раз в десять минут и пять в день по всему рабочему пространству, а уже добавленная заявка не получает ни одного. expired отмечает ожидающую подписку, последняя ссылка которой истекла.