Utvecklarguide · Registreringsformulär
Skapa din egen registreringsupplevelse.
Behåll din egen HTML, styling och webbplatsramverk. Anslut ditt formulär till ett publicerat smartest.email-formulär via dess publika registreringsändpunkt.
Guiden täcker
Publik formulärkonfiguration och registreringar från valfritt webbplatsursprung
Samtycke, validering, svar och anropsgränser
Använd URL:en från ditt formulär.
Skapa ett formulär under Registreringsformulär, lägg till ett obligatoriskt e-postfält och en obligatorisk samtyckesruta, och publicera det. Fliken Installera visar den exakta URL:en för formuläret.
Bas-URL
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Använd URL:en på formulärets flik Installera. Ersätt FORM_ID med det publicerade formulärets ID i exemplen nedan.
Skapa
Ange fält och en tydlig samtyckestext.
Publicera
Nya formulär börjar som utkast; publika adresser returnerar 404 tills de publiceras.
Integrera
Använd inbäddningskoden eller anropa de två publika ändpunkterna nedan.
Använd ditt eget HTML-formulär.
Direkt inskickning stöds. Skapa och publicera ett formulär i smartest.email för att definiera fält och samtyckestext, och använd sedan dess formulär-ID i ditt befintliga webbplatsformulär. Du kan välja den inbäddade formulärtypen utan att installera widgeten.
Din webbplats kan skicka med JavaScript fetch(), eller så kan din egen server vidarebefordra registreringen som JSON. Den publika ändpunkten behöver ingen API-nyckel, åtkomsttoken eller inbäddningsskript från smartest.email.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitErsätt FORM_ID med det publicerade formulärets UUID. Skicka Content-Type: application/json med innehållet nedan.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}Sätt consent utifrån besökarens uttryckliga val och visa formulärets samtyckestext och integritetsinformation. Behåll consent på toppnivån; placera konfigurerade kontaktfält inuti data. Inkludera varje obligatoriskt fält i ditt publicerade formulär.
En vanlig HTML-formuläråtgärd behöver en adapter
Ändpunkten accepterar endast JSON. Ett vanligt <form method="post" action="…"> skickar URL-kodad data eller multipart-data och får 415 JSON body required. Använd JavaScript-exemplet för webbläsaren nedan, eller skicka till din egen server och låt den skicka JSON till smartest.email.
Genom att hämta den publika konfigurationen hålls dina etiketter och valideringar i linje med det publicerade formuläret. Det krävs inte för varje inskickning. Integrationen hanterar sitt eget framgångsmeddelande eller omdirigering; denna ändpunkt svarar alltid med JSON.
Visa fälten du har publicerat.
Den publika ändpunkten behöver ingen åtkomsttoken. Hämta den när formuläret visas och använd returnerade fältnamn, samtyckestext och integritets-URL i ditt eget gränssnitt.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Returnerar 200 med säker visningsdata för ett aktivt formulär. Varje lyckad hämtning ökar visningsantalet; undvik upprepade kontrollanrop.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsFärdigt skript för inbäddad widget eller popup-widget. Använd den exakta skript-URL:en från Installera om du inte behöver ett eget gränssnitt.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingHostad registreringssida för ett aktivt formulär.
{
"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"
}Svaret kan innehålla ytterligare konfigurerade fält, val och valideringsregler. successAction beskriver beteendet för den färdiga widgeten; direkt inskickning returnerar fortfarande det generiska JSON-svaret nedan. Skriptet och den hostade sidan returnerar 404 för utkast samt avpublicerade, ogiltiga eller okända formulär.
Skicka samtycke tillsammans med uppgifterna.
Skicka JSON efter att besökaren uttryckligen valt att ta emot marknadsföringsmejl. Samtyckesflaggan hör hemma på toppnivån; placera inte consent inuti data.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitIngen åtkomsttoken. Skicka Content-Type: application/json och {data:{email:...},consent:true}. Returnerar samma generiska framgångssvar för nya och befintliga adresser.
<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>Ersätt FORM_ID med formulärets UUID och ställ in reservlänken /privacy till din egen information om formuläret saknar konfigurerad privacyUrl. Exemplet hanterar de två obligatoriska fälten; visa och skicka eventuella ytterligare obligatoriska fält från din publicerade konfiguration.
Godkänt svar
{"success":true,"message":"Thank you for subscribing."}Svaret avslöjar avsiktligt inte om en adress redan finns. Befintliga prenumeranter och avregistrerade kontakter behåller sin status; endast en ny godkänd adress lägger till en prenumerant och en samtyckespost.
Skicka endast namn som finns i den publicerade fields listan. Obligatoriska fält måste anges. För extra fält skickas kryssrutevärden som booleska värden, tal som numeriska strängar, datum som YYYY-MM-DD, och värden för val eller alternativknappar exakt som listade i options. API:et validerar uppgifterna igen på servern.
Den valfria egenskapen på toppnivån website är en spamfälla. Utelämna den eller lämna den tom vid vanlig inskickning. Ett icke-tomt värde returnerar det generiska framgångssvaret utan att lägga till en kontakt; det är inte ett fält för besökarens webbplatsadress.
Hantera fel och trafikgränser.
Publika formulärändpunkter tillåter GET-, POST- och OPTIONS-anrop från externa webbplatser med Content-Type- och Accept-rubriker. Använd credentials: omit i webbläsaranrop; inga kontocookies, Authorization-rubriker eller API-nycklar behövs.
| Status | Betydelse |
|---|---|
| 200 | Konfiguration eller godkänd inskickning; en dubblettadress får samma svar vid inskickning. |
| 400 / 415 | Felaktig JSON / anropet är inte application/json. |
| 404 | Okänt, utkast, avpublicerat eller ogiltigt formulär. |
| 409 | Kontot har nått sin kontaktgräns. |
| 413 / 422 | Innehållet överstiger 16 KiB / samtycke eller fältdata är ogiltigt. |
| 429 | Anropsgränsen nådd; webbläsarkod kan använda retry_after i JSON-innehållet. Serverintegrationer kan också läsa Retry-After. |
Fel använder {"error":true,"message":"..."}; fel för anropsgränser innehåller också retry_after i sekunder. Formulär tillåter upp till 30 förfrågningar per IP-adress och minut, varav högst 10 inskick. Webbplatsens innehållssäkerhetspolicy måste tillåta https://api.smartest.email i connect-src; den färdiga inbäddningen behöver den också i script-src.
När din egen server vidarebefordrar inskick delar de serverns utgående IP-adress vid begränsning av antalet förfrågningar.
Samtycke och leverans
En ny godkänd registrering skapar en prenumererande kontakt och sparar formulärets samtyckestext, tid och angivet anropsursprung. Ditt gränssnitt måste visa formulärets samtyckestext och integritetsinformation innan besökaren skickar. Det registrerade anropsursprunget bevisar ingen identitet. Ändpunkten använder enkel opt-in; den skickar inget bekräftelsemejl och verifierar inte ägandet av adressen.

