Guida per sviluppatori · Moduli di iscrizione
Crea la tua esperienza di iscrizione.
Mantieni il tuo HTML, lo stile e il framework del sito. Collega il modulo personalizzato a un modulo pubblicato su smartest.email tramite il suo endpoint pubblico di iscrizione.
Questa guida include
Configurazione pubblica dei moduli e iscrizioni da qualsiasi origine web
Consenso, validazione, risposte e limiti delle richieste
Usa l’URL del modulo.
Crea un modulo in Moduli di iscrizione, aggiungi un campo e-mail obbligatorio e una casella di consenso obbligatoria, poi pubblicalo. La scheda Installa mostra l’URL esatto del modulo.
URL di base
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Usa l’URL mostrato nella scheda Installa del modulo. Negli esempi qui sotto, sostituisci FORM_ID con l’ID del modulo pubblicato.
Crea
Imposta i campi e un testo di consenso chiaro.
Pubblica
I nuovi moduli partono come bozze; le rotte pubbliche restituiscono 404 fino alla pubblicazione.
Integra
Usa il codice da incorporare oppure chiama i due endpoint pubblici seguenti.
Usa il tuo modulo HTML.
L’invio diretto è supportato. Crea e pubblica un modulo su smartest.email per definirne i campi e il testo del consenso, poi usa il suo ID nel modulo già presente sul sito. Puoi scegliere il tipo di modulo incorporato senza installare il widget.
Il tuo sito può inviare tramite JavaScript fetch(), oppure il tuo server può inoltrare l’iscrizione come JSON. L’endpoint pubblico non richiede chiavi API, token di accesso o script incorporati di smartest.email.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitSostituisci FORM_ID con l’UUID del modulo pubblicato. Invia Content-Type: application/json con i dati seguenti.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}Imposta consent in base alla scelta esplicita del visitatore e mostra il testo del consenso e l’informativa sulla privacy del modulo. Mantieni consent al livello principale; inserisci i campi di contatto configurati all’interno di data. Includi tutti i campi obbligatori del modulo pubblicato.
L’azione di un modulo HTML semplice richiede un adattatore
L’endpoint accetta solo JSON. Un normale <form method="post" action="…"> invia dati URL-encoded o multipart e riceve 415 JSON body required. Usa l’ esempio JavaScript per browser qui sotto, oppure invia al tuo server e fai in modo che invii JSON a smartest.email.
Recuperare la configurazione pubblica mantiene i testi e la validazione allineati al modulo pubblicato. Non è necessario farlo per ogni invio. L’integrazione gestisce il proprio messaggio di successo o reindirizzamento; questo endpoint risponde sempre in JSON.
Mostra i campi che hai pubblicato.
Questo endpoint pubblico non richiede un token di accesso. Recuperalo quando mostri un modulo e usa nell’interfaccia i nomi dei campi, il testo del consenso e l’URL della privacy restituiti.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Restituisce 200 con dati sicuri per mostrare un modulo attivo. Ogni recupero riuscito incrementa il numero di visualizzazioni; evita il polling.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsScript di widget pronto all’uso, in linea o popup. Usa l’URL esatto dello script dalla scheda Installa se non ti serve un’interfaccia personalizzata.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingPagina di iscrizione ospitata per un modulo attivo.
{
"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"
}La risposta può includere altri campi, opzioni e regole di validazione configurati. successAction descrive il comportamento del widget pronto all’uso; l’invio diretto restituisce comunque la risposta JSON generica seguente. Lo script e la pagina ospitata restituiscono 404 per moduli in bozza, non pubblicati, non validi o sconosciuti.
Invia il consenso insieme ai dati.
Invia JSON dopo che il visitatore ha scelto esplicitamente di ricevere e-mail di marketing. L’indicatore del consenso va al livello principale; non inserire consent all’interno di data.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitNessun token di accesso. Invia Content-Type: application/json e {data:{email:...},consent:true}. Restituisce la stessa risposta generica di successo per indirizzi nuovi ed esistenti.
<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>Sostituisci FORM_ID con l’UUID del modulo e imposta il link di riserva /privacy alla tua informativa se il modulo non ha un privacyUrlconfigurato. Questo esempio gestisce i due campi obbligatori; mostra e invia tutti gli altri campi obbligatori presenti nella configurazione pubblicata.
Risposta di accettazione
{"success":true,"message":"Thank you for subscribing."}La risposta non indica intenzionalmente se un indirizzo esiste già. I contatti esistenti, iscritti o disiscritti, mantengono lo stato attuale; solo un nuovo indirizzo accettato aggiunge un iscritto e una registrazione del consenso.
Invia solo i nomi presenti nell’array pubblicato fields . I campi obbligatori devono essere forniti. Per i campi aggiuntivi, invia le caselle di selezione come booleani, i numeri come stringhe numeriche, le date come YYYY-MM-DD, e i valori di selezione o scelta singola esattamente come elencati in options. L’API convalida nuovamente i dati sul server.
La proprietà facoltativa al livello principale website è una trappola antispam. Omettila o lasciala vuota per un invio normale. Un valore non vuoto restituisce la risposta generica di successo senza aggiungere un contatto; non è un campo per l’URL del sito del visitatore.
Gestisci gli errori e i limiti di traffico.
Gli endpoint pubblici dei moduli consentono richieste GET, POST e OPTIONS tra origini diverse da siti esterni con gli header Content-Type e Accept. Usa credentials: omit nelle richieste del browser; non servono cookie dell’account, header Authorization o chiavi API.
| Stato | Significato |
|---|---|
| 200 | Configurazione o invio accettato; un indirizzo duplicato riceve la stessa risposta di invio. |
| 400 / 415 | JSON non valido / la richiesta non è application/json. |
| 404 | Modulo sconosciuto, in bozza, non pubblicato o non valido. |
| 409 | L’account ha raggiunto il limite di contatti. |
| 413 / 422 | Il corpo supera 16 KiB / il consenso o i dati dei campi non sono validi. |
| 429 | Limite delle richieste raggiunto; il codice nel browser può usare retry_after nel corpo JSON. Le integrazioni server possono anche leggere Retry-After. |
Gli errori usano {"error":true,"message":"..."}; gli errori relativi al limite delle richieste includono anche retry_after in secondi. I moduli consentono fino a 30 richieste per IP al minuto, inclusi al massimo 10 invii. La politica di sicurezza dei contenuti del tuo sito deve consentire https://api.smartest.email in connect-src; anche il codice incorporato pronto all’uso richiede questa autorizzazione in script-src.
Quando il tuo server inoltra gli invii, questi condividono il suo IP in uscita ai fini dei limiti di frequenza delle richieste.
Consenso e consegna
Una nuova iscrizione accettata crea un contatto iscritto e salva il testo del consenso del modulo, l’ora e l’origine fornita nella richiesta. L’interfaccia personalizzata deve mostrare il testo del consenso e l’informativa sulla privacy prima dell’invio. L’origine registrata non prova l’identità. Questo endpoint usa l’iscrizione semplice; non invia un’e-mail di conferma né verifica la proprietà dell’indirizzo.

