Como funcionam os formulários

Um formulário guarda duas cópias do que os visitantes veem. document é o rascunho que edita, e publishedDocument é o que a página alojada, a incorporação e o endpoint de inscrição usam. Guardar só altera o rascunho, e POST /forms/{id}/publish copia-o para a versão ativa. hasUnpublishedChanges indica-lhe que as duas diferem.

• —draft: nunca publicado. Ninguém o pode ver nem inscrever-se através dele.
• —live: publicado e a aceitar inscrições.
• —paused: publicado mas fechado. A página mostra a mensagem de encerramento dos textos do formulário e as inscrições são recusadas.

As settings são outra coisa: para onde vão as inscrições, a dupla confirmação, o remetente, o que acontece após a inscrição e quem é notificado de cada inscrição. Aplicam-se assim que são guardadas, publicadas ou não.

Um documento é uma lista de fields, os textos de copy à sua volta e um style. Cada campo de entrada tem uma key, o nome com que a sua resposta é enviada: uma letra minúscula seguida de até 39 letras minúsculas, algarismos ou sublinhados, única no formulário e nunca a começar por oe_. Todos os formulários têm exatamente um campo email, com a chave email e obrigatório.

• —Campos de entrada: email, text, textarea, number, phone, url e date.
• —Escolhas: select, radio e checkboxes, cada um com options.
• —checkbox para um sim ou não, e consent para uma caixa que tem de ser assinalada quando é obrigatória.
• —audiences deixa a pessoa escolher listas: cada value de opção é um id de audiência deste espaço de trabalho.
• —hidden leva um valor que o visitante nunca vê: o que a sua página envia, ou então o seu defaultValue, como o nome de uma campanha.
• —heading, paragraph e divider só servem para dispor o formulário e não enviam nada.

Defina mapsTo como firstName, lastName ou name num campo de texto, e a resposta passa a ser o nome do contacto que a inscrição cria. Um contacto que já existe mantém o seu nome. Cada resposta fica guardada na submissão, com a etiqueta que tinha, para que as submissões antigas continuem a ler-se corretamente depois de o formulário mudar.

Publique primeiro. Depois use a das três opções que melhor servir a página. Todas chegam ao mesmo formulário e contam as mesmas inscrições. As visualizações só são contadas na página alojada e na incorporação, por isso as inscrições feitas através do seu próprio HTML ou código aumentam a taxa de conversão.

• —A página alojada em url, uma página própria para a qual pode criar ligações a partir de qualquer lado.
• —O script de incorporação, que coloca o formulário na sua página numa moldura que ajusta sozinha o seu tamanho.
• —O seu próprio HTML ou código, a enviar as respostas para 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>

Um formulário HTML simples é redirecionado para a página de agradecimento, ou para settings.redirectUrl. O código que envia JSON recebe antes uma resposta JSON, descrita na página do endpoint de inscrição.

Com settings.doubleOptIn ativado, uma inscrição é guardada como pending e a pessoa recebe por email uma ligação enviada a partir de settings.senderAddress, um endereço deste espaço de trabalho. A pessoa entra nas audiências quando a abre. A ligação funciona durante sete dias. Uma pessoa que antes cancelou a subscrição de uma audiência só volta a ficar subscrita desta forma, nunca através de um formulário sem dupla confirmação. Inscrever-se de novo antes de confirmar atualiza a inscrição pendente em vez de acrescentar outra.

Para proteger as pessoas a quem envia emails, um endereço recebe no máximo uma confirmação por formulário a cada dez minutos e cinco por dia em todo o espaço de trabalho. Pode aprovar uma inscrição pendente por si próprio, ou enviar-lhe uma nova ligação.

• —Ler requer forms:read e alterar requer forms:write. Aprovar uma inscrição requer também contacts:write, porque adiciona um contacto.
• —Tudo o que faz um formulário enviar correio requer também emails:send: ativar a dupla confirmação, definir o remetente ou o email de confirmação, publicar ou retomar um formulário com dupla confirmação, e reenviar uma confirmação.
• —Uma chave de API e o proprietário veem todos os formulários do espaço de trabalho. Uma aplicação que um membro ligou só vê os formulários que esse membro criou, e só as audiências que esse membro criou, além das integradas.
• —Criar, atualizar, publicar, retomar ou duplicar um formulário cujo remetente ou endereços a notificar fiquem fora do que uma chave ou aplicação limitada pode alcançar dá um 422 capability_unsupported.
• —Uma chave ou aplicação limitada a alguns endereços só pode definir como remetente e como endereços a notificar endereços que detenha.
• —Eliminar um formulário pede um código de verificação a uma aplicação OAuth, como as outras alterações destrutivas. Uma chave de API nunca precisa de um.

Os webhooks form.submitted e form.confirmed informam os seus sistemas sobre cada inscrição. Um webhook limitado a alguns endereços nunca os recebe, porque as inscrições pertencem a todo o espaço de trabalho.

• —Um campo chamado oe_website é uma armadilha para bots: deixe-o vazio e fora do ecrã, como faz o HTML acima. Uma inscrição que o preencha recebe uma resposta normal e é descartada.
• —A página alojada e a incorporação verificam também uma hora de início assinada, e um formulário devolvido mais depressa do que uma pessoa o conseguiria preencher é descartado da mesma forma.
• —Uma mesma rede pode enviar 40 inscrições em dez minutos, somando todos os seus formulários e seja qual for o resultado. Depois disso, o código que envia JSON recebe 429 form_rate_limited, e um formulário HTML simples vai para a página alojada com ?outcome=limited.
• —Um espaço de trabalho comporta 100 formulários por omissão.

Tudo o que está aqui existe também no SDK como openemail.forms e na CLI como openemail forms, e o servidor MCP tem ferramentas de formulários, por isso um agente pode criar, publicar e acompanhar um formulário. Através do MCP, o cliente escreve ele próprio o design e passa-o como document.

Enviar dados por POST para subscribeUrl a partir do seu próprio código não precisa de credencial. Envie as respostas como JSON, acrescente 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. Todas as inscrições a partir de uma mesma rede partilham o 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 a importação para uma audiência.