Формы
`forms.list`, `get`, `create`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `listStarters`, `getStarter`, `listSubmissions`, `getSubmission`, `deleteSubmission`, `deleteSubmissions`, `approveSubmission`, `resendConfirmation` и `subscribe`.
Все методы
const form = await openemail.forms.create({ name: 'Newsletter sign-up', starter: 'newsletter', settings: { audienceIds: ['aud_4c1b8e2a7d9f05c36b4e8a71'] }, publish: true,}) console.log(form.url, form.subscribeUrl) const saved = await openemail.forms.update(form.id, { settings: { doubleOptIn: true, senderAddress: '[email protected]' }, expectedUpdatedAt: form.updatedAt,}) const signup = await openemail.forms.subscribe(form.id, { email: '[email protected]', first_name: 'Ann', consent: true,}) for await (const submission of openemail.forms.iterateSubmissions(form.id, { status: 'pending' })) { if (submission.expired) await openemail.forms.resendConfirmation(form.id, submission.id)} const stats = await openemail.forms.analytics(form.id, { days: 30 })const starters = await openemail.forms.listStarters() await openemail.forms.pause(form.id)await openemail.forms.resume(form.id)const copy = await openemail.forms.duplicate(form.id)await openemail.forms.delete(copy.id) console.log(saved.senderIssue, signup.outcome, stats.totals.conversion, starters.length)Форма хранит черновик document и publishedDocument, который видят посетители. update меняет черновик и настройки, а publish публикует черновик. Настройки вступают в силу сразу, опубликована форма или нет, а expectedUpdatedAt отклоняет с 409 version_conflict сохранение, которое перезаписало бы чужое.
Для чтения нужен forms:read, а для изменения нужен forms:write. Для approveSubmission нужен также contacts:write, потому что этот метод добавляет контакт. Для resendConfirmation нужен также emails:send, как и для вызова, который заставляет форму отправлять почту: включающего doubleOptIn, задающего senderAddress или письмо с подтверждением, публикующего или возобновляющего форму с двойным подтверждением. delete требует от токена доступа OAuth код подтверждения, а от API-ключа никогда.
subscribe подписывает человека так же, как страница формы, и не отправляет учётных данных, даже из клиента, у которого они есть. Все подписки из одной сети делят один лимит в 40 подписок на каждые десять минут, поэтому сервер, который передаёт подписки многих людей, быстро его исчерпает: людей, которых вы уже знаете, лучше добавляйте через audiences.importContacts. Передайте страницу, на которой была форма, как oe_source, не указывайте oe_started, а oe_website отправляйте пустым или не отправляйте вовсе.
Ответ 422 от subscribe означает invalid_form_submission, и fields в ошибке перечисляет каждый отсутствующий или недопустимый ответ в виде { key, error } с причинами, такими как required, email и option. Клиент предназначен для серверов. В браузере отправляйте ответы через fetch на subscribeUrl формы, телом в JSON или с заголовком Accept: application/json, и он отвечает в JSON на запросы с любого источника. Если нет ни того, ни другого, он отвечает перенаправлением 303 на размещённую у нас страницу.
Ответ: FormDetailResource
list разрешается в одну страницу FormResource, от новых к старым, без document и settings, а listAll и iterate проходят все страницы. get, create, update, publish, pause, resume и duplicate разрешаются в FormDetailResource, который добавляет document, publishedDocument, settings, audiences, senderIssue и senderProblem.
idstring- Постоянный идентификатор: `frm_` и 24 шестнадцатеричных символа.
status'draft' | 'live' | 'paused'- `draft` до первой публикации, затем `live`, пока форма принимает подписки, и `paused`, пока не принимает. Форма никогда не возвращается в `draft`.
urlstring- Размещённая у нас страница опубликованной формы, чтобы делиться ею как ссылкой.
subscribeUrlstring- Куда обычная HTML-форма или `fetch` отправляет ответы.
documentFormDocument- Черновик: `fields` по порядку, окружающие их тексты `copy` и оформление `style`.
publishedDocumentFormDocument | null- То, что посетители видят сейчас. Null до первой публикации.
settingsFormSettings- Куда попадают подписки и что происходит после подписки: `audienceIds`, `doubleOptIn`, `senderAddress`, письмо с подтверждением, `successAction`, `redirectUrl` и `notifyAddresses`.
hasUnpublishedChangesboolean- True, когда черновик отличается от того, что видят посетители. Всегда false до первой публикации.
senderIssue'missing' | 'not_sendable' | 'not_allowed' | null- Почему форма с двойным подтверждением сейчас не может отправлять письма с подтверждением, или null, когда может.
statsFormStats- `views`, `submissions`, `added`, `pending` и `lastSubmittedAt`, подсчитанные в момент чтения.
Заявки
listSubmissions выдаёт страницы от новых к старым, с q для поиска по адресам электронной почты и status для pending или added, а listAllSubmissions и iterateSubmissions проходят все страницы. Каждый FormSubmissionResource хранит ответы в том виде, в каком они были отправлены, вместе с подписями, поэтому читается правильно и после изменения формы.
resendConfirmation разрешается в заявку с confirmationSent. Он равен false, когда ничего не ушло: один адрес получает одно подтверждение на форму раз в десять минут и пять в день по всему рабочему пространству, а уже добавленная заявка не получает ни одного. expired отмечает ожидающую подписку, у которой истекла последняя ссылка.
