Formulários
`forms->list`, `listAll`, `iterate`, `get`, `create`, `design`, `redesign`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `listStarters`, `getStarter`, `listSubmissions`, `getSubmission`, `deleteSubmission`, `deleteSubmissions`, `approveSubmission`, `resendConfirmation` e `subscribe`.
Todos os métodos
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;Um formulário guarda um rascunho document e o publishedDocument que os visitantes veem. update altera o rascunho e as definições, e publish ativa o rascunho. As definições têm efeito de imediato, publicadas ou não, e expectedUpdatedAt recusa com um 409 version_conflict, lançado como ConflictException, uma alteração guardada que substituiria a de outra pessoa.
Os campos de um formulário são as chaves de um único array com os nomes em camelCase da API (expectedUpdatedAt, doubleOptIn), enquanto os filtros e as opções são argumentos nomeados (status: em listSubmissions, offsetMinutes: em analytics). Um formulário volta como um array com chaves em camelCase, por isso $form['subscribeUrl'] lê o endereço que recebe as inscrições.
design cria um novo formulário em rascunho a partir de uma descrição escrita, como faz Criar com IA na página Formulários, e redesign aplica instruções escritas ao rascunho de um formulário, como faz Pedir à IA no construtor de formulários. Cada um gasta uma ação de IA e escreve apenas o rascunho, por isso os visitantes não veem nada de novo até publish.
Ler requer forms:read e alterar requer forms:write. approveSubmission requer também contacts:write, porque adiciona um contacto. resendConfirmation requer também emails:send, tal como uma chamada que faça o formulário enviar correio: ativar doubleOptIn, definir senderAddress ou o email de confirmação, ou ainda publicar ou retomar um formulário com dupla confirmação. delete pede um código de verificação a um token de acesso OAuth, e a uma chave de API nunca. Enquanto o token não tiver um, delete lança um PermissionException cujo isStepUpRequired() é true.
subscribe inscreve alguém tal como a página do formulário faz e não envia nenhuma credencial, mesmo a partir de um cliente que tenha uma, por isso apiKey: é ignorado. As respostas são o seu segundo argumento, um único array com as chaves dos campos do formulário. Todas as inscrições a partir de uma mesma rede partilham um limite de 40 a cada dez minutos, por isso um servidor que reencaminha inscrições de muitas pessoas atinge-o depressa: em vez disso, adicione as pessoas que já conhece com audiences->importContacts. Acima do limite, a chamada lança um RateLimitException. Passe a página onde estava o formulário como oe_source, deixe de fora oe_started, e envie oe_website vazio ou não o envie de todo.
Um 422 de subscribe é invalid_form_submission, lançado como ValidationException, e o fields da exceção lista cada resposta em falta ou inválida como um array com key e error, com motivos como required, email e option. OpenEmail\Constants\FormFieldErrors nomeia todos os motivos. O pacote corre num servidor. Um navegador envia ele próprio as respostas para o subscribeUrl do formulário, como corpo JSON ou com um cabeçalho Accept: application/json, e recebe JSON de volta a partir de qualquer origem. Sem nenhum dos dois, recebe um redirecionamento 303 para a página alojada.
Resposta: um formulário
list devolve uma OpenEmail\Result\Page de formulários, dos mais recentes para os mais antigos, sem document e settings. listAll devolve todos os formulários num único array, e iterate devolve um Generator que percorre todas as páginas um formulário de cada vez. get, create, update, publish, pause, resume e duplicate devolvem o formulário completo como um array, que acrescenta document, publishedDocument, settings, audiences, senderIssue e senderProblem.
idstring- O identificador duradouro: `frm_` seguido de 24 caracteres hexadecimais.
statusstring- `draft` até à primeira publicação, depois `live` enquanto aceita inscrições e `paused` enquanto não as aceita. Um formulário nunca volta a `draft`. `OpenEmail\Constants\FormStatuses` nomeia os três.
urlstring- A página alojada do formulário publicado, para partilhar como ligação.
subscribeUrlstring- Para onde um formulário HTML simples, ou um script no navegador, envia as respostas.
documentarray- O rascunho: os `fields` por ordem, os textos de `copy` à sua volta e o `style`.
publishedDocumentarray or null- O que os visitantes veem agora, ou null até à primeira publicação.
settingsarray- Para onde vão as inscrições e o que acontece depois de cada uma: `audienceIds`, `doubleOptIn`, `senderAddress`, o email de confirmação, `successAction`, `redirectUrl` e `notifyAddresses`.
hasUnpublishedChangesbool- True quando o rascunho difere do que os visitantes veem. Sempre false antes da primeira publicação.
senderIssuestring or null- Porque é que um formulário com dupla confirmação não pode enviar os seus emails de confirmação neste momento: `missing`, `not_sendable` ou `not_allowed`. É null quando pode. `OpenEmail\Constants\FormSenderIssues` nomeia os três.
statsarray- `views`, `submissions`, `added`, `pending` e `lastSubmittedAt`, contados no momento da leitura.
Submissões
listSubmissions devolve páginas das mais recentes para as mais antigas, com q: para pesquisar endereços de email e status: para pending ou added, e listAllSubmissions e iterateSubmissions percorrem todas as páginas. OpenEmail\Constants\FormSubmissionStatuses nomeia os dois estados. Cada submissão é um array que guarda as respostas tal como foram enviadas, etiquetas incluídas, para que continue a ler-se corretamente depois de o formulário mudar.
resendConfirmation devolve a submissão com confirmationSent. É false quando nada saiu: um endereço recebe uma confirmação por formulário a cada dez minutos e cinco por dia em todo o espaço de trabalho, e uma submissão já adicionada não recebe nenhuma. expired assinala uma inscrição pendente cuja ligação mais recente expirou.