Guide développeur · Formulaires d’inscription
Créez votre propre parcours d’inscription.
Conservez votre HTML, votre style et votre framework. Reliez votre formulaire à un formulaire smartest.email publié via son point d’accès public d’inscription.
Ce guide couvre
Configuration publique et inscriptions depuis toute origine de site web
Consentement, validation, réponses et limites de requêtes
Utilisez l’URL de votre formulaire.
Créez un formulaire avec un champ e-mail et une case de consentement obligatoires, puis publiez-le. L’onglet Installation affiche l’URL exacte.
URL de base
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Utilisez l’URL affichée dans l’onglet Installer de votre formulaire. Remplacez FORM_ID par l’identifiant de votre formulaire publié dans les exemples ci-dessous.
Créer
Définissez les champs et un libellé de consentement clair.
Publier
Les nouveaux formulaires sont des brouillons ; les routes publiques renvoient 404 jusqu’à leur publication.
Intégrer
Utilisez le code d’intégration ou les deux points d’accès publics ci-dessous.
Utilisez votre propre formulaire HTML.
L’envoi direct est pris en charge. Créez et publiez un formulaire dans smartest.email pour définir ses champs et son consentement, puis utilisez son ID dans votre site. Le type intégré peut être choisi sans installer le widget.
Votre site peut envoyer avec JavaScript fetch(), ou votre serveur peut transmettre l’inscription en JSON. Le point d’accès public ne nécessite ni clé API, ni jeton d’accès, ni script d’intégration smartest.email.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitRemplacez FORM_ID par l’UUID du formulaire publié. Envoyez Content-Type: application/json avec le contenu ci-dessous.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}Définissez consent selon le choix explicite du visiteur et affichez le texte de consentement et la notice de confidentialité. Gardez consent au niveau supérieur ; placez les champs de contact configurés dans data. Incluez tous les champs obligatoires du formulaire publié.
Un formulaire HTML simple nécessite un adaptateur
Le point d’accès accepte uniquement JSON. Un simple <form method="post" action="…"> envoie des données encodées en URL ou multipart et reçoit 415 JSON body required. Utilisez l’ exemple JavaScript pour navigateur ci-dessousou envoyez à votre serveur, qui transmettra le JSON à smartest.email.
Récupérer la configuration publique garde les libellés et la validation alignés avec le formulaire publié. Ce n’est pas requis à chaque envoi. Votre intégration gère son message de succès ou sa redirection ; le point d’accès répond toujours en JSON.
Affichez les champs publiés.
Ce point d’accès public ne nécessite pas de jeton. Récupérez-le à l’affichage du formulaire, puis utilisez les noms de champs, le consentement et l’URL de confidentialité dans votre interface.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Renvoie 200 avec les données d’affichage sûres d’un formulaire actif. Chaque requête réussie augmente le nombre de vues ; évitez les requêtes répétées.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsScript de widget intégré ou popup prêt à l’emploi. Utilisez l’URL exacte de l’onglet Installation si vous n’avez pas besoin d’interface personnalisée.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingPage d’inscription hébergée pour un formulaire actif.
{
"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 réponse peut inclure d’autres champs configurés, choix et règles de validation. successAction décrit le comportement du widget prêt à l’emploi ; l’envoi direct renvoie toujours la réponse JSON générique ci-dessous. Le script et la page hébergée renvoient 404 pour les formulaires brouillons, non publiés, invalides ou inconnus.
Envoyez le consentement avec les données.
Envoyez du JSON après le choix explicite du visiteur de recevoir du marketing. Le consentement est au niveau supérieur, pas dans data.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitAucun jeton. Envoyez Content-Type: application/json et {data:{email:...},consent:true}. Renvoie le même succès générique pour les adresses nouvelles et existantes.
<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>Remplacez FORM_ID par l’UUID de votre formulaire et définissez le lien de secours /privacy vers votre propre notice si le formulaire n’a pas de privacyUrlconfigurée. Cet exemple couvre les deux champs obligatoires ; affichez et envoyez aussi tous les autres champs obligatoires de votre configuration publiée.
Réponse acceptée
{"success":true,"message":"Thank you for subscribing."}La réponse ne révèle pas si une adresse existe. Les contacts existants abonnés et désinscrits gardent leur état ; seule une nouvelle adresse acceptée ajoute un abonné et un consentement enregistré.
Envoyez uniquement les noms présents dans le tableau publié fields . Les champs obligatoires doivent être fournis. Envoyez les cases supplémentaires comme booléens, les nombres comme chaînes numériques, les dates au format YYYY-MM-DDet les valeurs de sélection exactement comme dans options. L’API valide de nouveau les données côté serveur.
La propriété facultative website au niveau supérieur est un piège antispam. Omettez-la ou laissez-la vide pour un envoi normal. Une valeur non vide renvoie le succès générique sans ajouter de contact ; ce n’est pas un champ pour le site du visiteur.
Gérez les erreurs et limites de trafic.
Les points d’accès publics autorisent les requêtes GET, POST et OPTIONS d’autres sites avec Content-Type et Accept. Utilisez credentials: omit dans le navigateur ; aucun cookie de compte, en-tête Authorization ou clé API n’est nécessaire.
| État | Signification |
|---|---|
| 200 | Configuration ou envoi accepté ; une adresse en double reçoit la même réponse. |
| 400 / 415 | JSON mal formé / requête non application/json. |
| 404 | Formulaire inconnu, brouillon, non publié ou invalide. |
| 409 | Le compte a atteint sa limite de contacts. |
| 413 / 422 | Contenu supérieur à 16 Kio / consentement ou données invalides. |
| 429 | Limite atteinte ; le navigateur peut utiliser retry_after dans le JSON. Les intégrations serveur peuvent aussi lire Retry-After. |
Les erreurs utilisent {"error":true,"message":"..."}; les erreurs de limite incluent aussi retry_after en secondes. Les formulaires autorisent jusqu’à 30 requêtes par adresse IP et par minute, dont au maximum 10 envois. La politique de sécurité du contenu de votre site doit autoriser https://api.smartest.email dans connect-src; le widget intégré le nécessite aussi dans script-src.
Lorsque votre propre serveur transmet les envois, ils partagent son adresse IP sortante pour la limitation des requêtes.
Consentement et livraison
Une nouvelle inscription acceptée crée un contact abonné et enregistre le consentement, l’heure et l’origine fournie. Votre interface doit afficher le consentement et la notice avant l’envoi. L’origine enregistrée ne prouve pas l’identité. Ce point d’accès utilise le simple opt-in : il n’envoie pas de confirmation et ne vérifie pas la propriété de l’adresse.

