Ontwikkelaarshandleiding · Aanmeldformulieren
Maak je eigen aanmeldproces.
Behoud je eigen HTML, vormgeving en websiteframework. Koppel je formulier via het openbare aanmeldendpoint aan een gepubliceerd smartest.email-formulier.
Deze handleiding behandelt
Openbare formulierconfiguratie en aanmeldingen vanaf elke website-oorsprong
Toestemming, validatie, antwoorden en aanvraaglimieten
Gebruik de URL van je formulier.
Maak een formulier onder Aanmeldformulieren, voeg een verplicht e-mailveld en een verplicht toestemmingsvakje toe en publiceer het. Het tabblad Installeren toont de exacte URL.
Basis-URL
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Gebruik de URL op het tabblad Installeren van je formulier. Vervang FORM_ID in de onderstaande voorbeelden door de ID van je gepubliceerde formulier.
Maken
Stel je velden en een duidelijke toestemmingstekst in.
Publiceren
Nieuwe formulieren beginnen als concept; openbare routes geven 404 tot publicatie.
Integreren
Gebruik de insluitcode of roep de twee openbare endpoints hieronder aan.
Gebruik je eigen HTML-formulier.
Direct inzenden wordt ondersteund. Maak en publiceer een formulier in smartest.email om velden en toestemmingstekst vast te leggen. Gebruik daarna de formulier-ID op je eigen website. Je kunt het ingesloten formuliertype kiezen zonder de widget te installeren.
Je website kan inzenden met JavaScript fetch(), of je server kan de aanmelding als JSON doorsturen. Het openbare endpoint vereist geen API-sleutel, toegangstoken of smartest.email-insluitscript.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitVervang FORM_ID door de UUID van je gepubliceerde formulier. Verstuur Content-Type: application/json met de inhoud hieronder.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}Stel consent in op basis van de uitdrukkelijke keuze van de bezoeker en toon de toestemmingstekst en privacyverklaring. Houd consent op het hoogste niveau; zet geconfigureerde contactvelden in data. Neem alle verplichte velden van je gepubliceerde formulier op.
Een gewoon HTML-formulier heeft een adapter nodig
Het endpoint accepteert alleen JSON. Een gewoon <form method="post" action="…"> verstuurt URL-gecodeerde of multipartgegevens en krijgt 415 JSON body required. Gebruik het JavaScript-browservoorbeeld hieronderof verstuur naar je eigen server en laat die JSON naar smartest.email sturen.
De openbare configuratie ophalen houdt labels en validatie gelijk aan het gepubliceerde formulier. Dit is niet vereist voor elke inzending. Je integratie regelt het eigen succesbericht of de omleiding; het endpoint antwoordt altijd met JSON.
Toon de velden die je hebt gepubliceerd.
Dit openbare endpoint vereist geen toegangstoken. Haal het op bij het tonen van een formulier en gebruik de geretourneerde veldnamen, toestemmingstekst en privacy-URL in je eigen interface.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Retourneert 200 met veilige weergavegegevens voor een actief formulier. Elke geslaagde aanvraag verhoogt het aantal weergaven; vermijd polling.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsKant-en-klaar inline- of popupscript. Gebruik de exacte script-URL uit Installeren als je geen eigen interface nodig hebt.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingGehoste aanmeldpagina voor een actief formulier.
{
"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"
}Het antwoord kan extra geconfigureerde velden, keuzes en validatieregels bevatten. successAction beschrijft het gedrag van de standaardwidget; direct inzenden geeft nog steeds het algemene JSON-antwoord hieronder. Het script en de gehoste pagina geven 404 voor concepten, niet-gepubliceerde, ongeldige of onbekende formulieren.
Verstuur toestemming met de gegevens.
Verstuur JSON nadat de bezoeker expliciet voor marketingmail kiest. Het toestemmingsveld hoort op het hoogste niveau, niet binnen data.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitGeen toegangstoken. Verstuur Content-Type: application/json en {data:{email:...},consent:true}. Geeft hetzelfde algemene succesantwoord voor nieuwe en bestaande adressen.
<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>Vervang FORM_ID door de UUID van je formulier en stel de terugval- /privacy link in op je eigen verklaring als het formulier geen privacyUrlheeft. Dit voorbeeld behandelt de twee verplichte velden; toon en verstuur ook alle extra verplichte velden uit je gepubliceerde configuratie.
Geaccepteerd antwoord
{"success":true,"message":"Thank you for subscribing."}Het antwoord vermeldt bewust niet of een adres al bestaat. Bestaande geabonneerde en afgemelde contacten behouden hun status; alleen een nieuw geaccepteerd adres voegt een abonnee en toestemmingsregistratie toe.
Verstuur alleen namen uit de gepubliceerde fields array. Verplichte velden moeten worden meegestuurd. Verstuur extra selectievakjes als booleans, getallen als numerieke strings, datums als YYYY-MM-DDen select- of radiowaarden exact zoals vermeld in options. De API valideert de gegevens opnieuw op de server.
De optionele eigenschap website op het hoogste niveau is een spamval. Laat deze weg of leeg bij normale inzendingen. Een niet-lege waarde geeft het algemene succesantwoord zonder contact toe te voegen; het is geen veld voor de website-URL van de bezoeker.
Verwerk fouten en verkeerslimieten.
Openbare formulierendpoints staan cross-origin GET-, POST- en OPTIONS-verzoeken toe met Content-Type- en Accept-headers. Gebruik credentials: omit in de browser; accountcookies, een Authorization-header en een API-sleutel zijn niet nodig.
| Status | Betekenis |
|---|---|
| 200 | Configuratie of geaccepteerde inzending; een dubbel adres krijgt hetzelfde antwoord. |
| 400 / 415 | Ongeldige JSON / verzoek is niet application/json. |
| 404 | Onbekend, concept-, niet-gepubliceerd of ongeldig formulier. |
| 409 | Het account heeft zijn contactlimiet bereikt. |
| 413 / 422 | Inhoud groter dan 16 KiB / toestemming of veldgegevens ongeldig. |
| 429 | Aanvraaglimiet bereikt; browsercode kan retry_after uit de JSON-inhoud gebruiken. Serverintegraties kunnen ook Retry-After. |
Fouten gebruiken {"error":true,"message":"..."}; limietfouten bevatten ook retry_after in seconden. Voor formulieren zijn maximaal 30 verzoeken per IP-adres per minuut toegestaan, waarvan maximaal 10 inzendingen. Het inhoudsbeveiligingsbeleid (CSP) van je website moet toegang toestaan tot https://api.smartest.email toestaan in connect-src; de standaardwidget vereist dit ook in script-src.
Wanneer je eigen server inzendingen doorstuurt, delen deze het uitgaande IP-adres van die server voor de verzoeklimiet.
Toestemming en bezorging
Een nieuwe geaccepteerde aanmelding maakt een geabonneerd contact en bewaart de toestemmingstekst, het tijdstip en de opgegeven oorsprong. Je interface moet vóór inzending de toestemmingstekst en privacyverklaring tonen. De vastgelegde oorsprong is geen identiteitsbewijs. Dit endpoint gebruikt single opt-in: het verstuurt geen bevestigingsmail en verifieert het eigendom van het adres niet.

