Guia para programadores · Formulários de inscrição
Crie a sua própria experiência de inscrição.
Mantenha o seu HTML, estilo e framework do site. Ligue o formulário personalizado a um formulário publicado em smartest.email através do ponto de acesso público de inscrição.
Este guia inclui
Configuração pública de formulários e inscrições a partir de qualquer origem de site
Consentimento, validação, respostas e limites de pedidos
Use o URL do formulário.
Crie um formulário em Formulários de inscrição, inclua um campo de e-mail obrigatório e uma caixa de consentimento obrigatória e publique-o. O separador Instalar apresenta o URL exato do formulário.
URL base
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Utilize o URL apresentado no separador Instalar do formulário. Substitua FORM_ID pelo ID do formulário publicado nos exemplos abaixo.
Criar
Defina os campos e um texto de consentimento claro.
Publicar
Os novos formulários começam como rascunhos; as rotas públicas devolvem 404 até à publicação.
Integrar
Use o código de incorporação ou chame os dois pontos de acesso públicos abaixo.
Use o seu próprio formulário HTML.
A submissão direta é suportada. Crie e publique um formulário em smartest.email para definir os campos e o texto de consentimento e use o respetivo ID no formulário existente do site. Pode escolher o tipo de formulário incorporado sem instalar o widget.
O seu site pode enviar através de JavaScript fetch(), ou o seu servidor pode encaminhar a inscrição como JSON. O ponto de acesso público não exige chave de API, token de acesso nem script incorporado de smartest.email.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitSubstitua FORM_ID pelo UUID do formulário publicado. Envie Content-Type: application/json com os dados abaixo.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}Defina consent a partir da escolha explícita do visitante e apresente o texto de consentimento e o aviso de privacidade do formulário. Mantenha consent no nível superior; coloque os campos de contacto configurados dentro de data. Inclua todos os campos obrigatórios do formulário publicado.
A ação de um formulário HTML simples precisa de um adaptador
O ponto de acesso aceita apenas JSON. Um <form method="post" action="…"> normal envia dados codificados em URL ou multipart e recebe 415 JSON body required. Use o exemplo de JavaScript para navegador abaixo, ou envie para o seu servidor e faça-o enviar JSON para smartest.email.
Consultar a configuração pública mantém os textos e a validação alinhados com o formulário publicado. Não é obrigatório fazê-lo para cada submissão. A integração gere a própria mensagem de sucesso ou redirecionamento; este ponto de acesso responde sempre em JSON.
Apresente os campos que publicou.
Este ponto de acesso público não exige token de acesso. Consulte-o ao apresentar um formulário e use os nomes dos campos, o texto de consentimento e o URL de privacidade devolvidos na sua interface.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Devolve 200 com dados seguros para apresentar um formulário ativo. Cada consulta bem-sucedida incrementa o número de visualizações; evite consultas repetitivas.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsScript de widget pronto a usar, incorporado na página ou em popup. Use o URL exato do script apresentado em Instalar se não precisar de uma interface personalizada.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingPágina de inscrição alojada para um formulário ativo.
{
"id": "FORM_ID",
"name": "Newsletter",
"organizationName": "Example Studio",
"type": "embedded",
"fields": [
{ "name": "email", "type": "email", "label": "Email address", "required": true },
{ "name": "consent", "type": "checkbox", "label": "I agree to receive email updates.", "required": true }
],
"styling": {},
"successAction": {},
"privacyUrl": "https://example.com/privacy"
}A resposta pode incluir outros campos, opções e regras de validação configurados. successAction descreve o comportamento do widget pronto a usar; a submissão direta continua a devolver a resposta JSON genérica abaixo. O script e a página alojada devolvem 404 para formulários em rascunho, não publicados, inválidos ou desconhecidos.
Envie o consentimento com os dados.
Envie JSON depois de o visitante escolher explicitamente receber e-mails de marketing. A indicação de consentimento deve estar no nível superior; não coloque consent dentro de data.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitSem token de acesso. Envie Content-Type: application/json e {data:{email:...},consent:true}. Devolve a mesma resposta genérica de sucesso para endereços novos e existentes.
<form id="signup-form">
<fieldset id="signup-fields" disabled>
<legend>Subscribe to email updates</legend>
<label id="email-label" for="signup-email">Email address</label>
<input id="signup-email" type="email" autocomplete="email" required>
<label for="signup-consent">
<input id="signup-consent" type="checkbox" required>
<span id="consent-label"></span>
</label>
<a id="privacy-link" href="/privacy">Privacy notice</a>
<button id="signup-submit" type="submit">Subscribe</button>
</fieldset>
<p id="signup-status" role="status" aria-live="polite"></p>
</form>
<script type="module">
const endpoint = "https://api.smartest.email/api/v1/public/forms/FORM_ID";
const form = document.querySelector("#signup-form");
const fields = document.querySelector("#signup-fields");
const button = document.querySelector("#signup-submit");
const status = document.querySelector("#signup-status");
let ready = false;
let submitting = false;
form.addEventListener("submit", async event => {
event.preventDefault();
if (!ready || submitting || !form.reportValidity()) return;
submitting = true;
button.disabled = true;
try {
const response = await fetch(endpoint + "/submit", {
method: "POST",
credentials: "omit",
headers: { "Content-Type": "application/json", "Accept": "application/json" },
body: JSON.stringify({
data: { email: document.querySelector("#signup-email").value.trim() },
consent: document.querySelector("#signup-consent").checked
})
});
const result = await response.json();
status.textContent = result.message || "Please try again.";
if (response.ok) form.reset();
} catch {
status.textContent = "Please try again.";
} finally {
submitting = false;
button.disabled = false;
}
});
try {
const response = await fetch(endpoint, { credentials: "omit" });
if (!response.ok) throw new Error("Signup form unavailable");
const config = await response.json();
document.querySelector("#email-label").textContent =
config.fields.find(field => field.name === "email").label;
document.querySelector("#consent-label").textContent =
config.fields.find(field => field.name === "consent").label;
if (config.privacyUrl) {
document.querySelector("#privacy-link").href = config.privacyUrl;
}
ready = true;
fields.disabled = false;
} catch (error) {
status.textContent = error.message;
}
</script>Substitua FORM_ID pelo UUID do formulário e defina a ligação alternativa /privacy para o seu aviso caso o formulário não tenha um privacyUrlconfigurado. Este exemplo trata dos dois campos obrigatórios; apresente e envie quaisquer outros campos obrigatórios da configuração publicada.
Resposta de aceitação
{"success":true,"message":"Thank you for subscribing."}A resposta não indica propositadamente se o endereço já existe. Os contactos existentes, inscritos ou com inscrição cancelada, mantêm o estado atual; apenas um novo endereço aceite adiciona um subscritor e um registo de consentimento.
Envie apenas nomes presentes na lista publicada fields . Os campos obrigatórios têm de ser enviados. Para campos adicionais, envie caixas de seleção como booleanos, números como cadeias numéricas, datas como YYYY-MM-DDe valores de seleção ou escolha única exatamente como indicados em options. A API volta a validar os dados no servidor.
A propriedade opcional de nível superior website é uma armadilha antisspam. Omita-a ou deixe-a vazia numa submissão normal. Um valor não vazio devolve a resposta genérica de sucesso sem adicionar um contacto; não é um campo para o URL do site do visitante.
Trate as falhas e os limites de tráfego.
Os pontos de acesso públicos de formulários permitem pedidos GET, POST e OPTIONS entre origens a partir de sites externos com os cabeçalhos Content-Type e Accept. Use credentials: omit nos pedidos do navegador; não são necessários cookies de conta, cabeçalho Authorization nem chave de API.
| Estado | Significado |
|---|---|
| 200 | Configuração ou submissão aceite; um endereço duplicado recebe a mesma resposta de submissão. |
| 400 / 415 | JSON malformado / o pedido não é application/json. |
| 404 | Formulário desconhecido, em rascunho, não publicado ou inválido. |
| 409 | A conta atingiu o limite de contactos. |
| 413 / 422 | O corpo excede 16 KiB / o consentimento ou os dados dos campos são inválidos. |
| 429 | Limite de pedidos atingido; o código no navegador pode usar retry_after no corpo JSON. As integrações de servidor também podem ler Retry-After. |
Os erros usam {"error":true,"message":"..."}; os erros de limite de pedidos também incluem retry_after em segundos. Os formulários permitem até 30 pedidos por IP por minuto, incluindo até 10 envios. A política de segurança de conteúdos do seu website tem de permitir https://api.smartest.email em connect-src; o código de incorporação pronto a usar também precisa dessa permissão em script-src.
Quando o seu próprio servidor reencaminha envios, estes partilham o IP de saída desse servidor para efeitos de limitação de pedidos.
Consentimento e entrega
Uma nova inscrição aceite cria um contacto inscrito e guarda o texto de consentimento do formulário, a hora e a origem fornecida no pedido. A interface personalizada deve apresentar o texto de consentimento e o aviso de privacidade antes da submissão. A origem registada do pedido não é prova de identidade. Este ponto de acesso usa inscrição simples; não envia um e-mail de confirmação nem verifica a titularidade do endereço.

