Utviklerveiledning · Påmeldingsskjemaer
Lag din egen påmeldingsopplevelse.
Behold egen HTML, utforming og nettstedsrammeverk. Koble skjemaet ditt til et publisert smartest.email-skjema via det offentlige påmeldingsendepunktet.
Veiledningen dekker
Offentlig skjemakonfigurasjon og påmeldinger fra alle nettstedsopprinnelser
Samtykke, validering, svar og frekvensgrenser
Bruk URL-en fra skjemaet ditt.
Opprett et skjema under Påmeldingsskjemaer, legg til et obligatorisk e-postfelt og en obligatorisk samtykkeboks, og publiser det. Fanen Installer viser den nøyaktige URL-en for skjemaet.
Basis-URL
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Bruk nettadressen på skjemaets Installer-fane. Erstatt FORM_ID med ID-en til det publiserte skjemaet i eksemplene nedenfor.
Opprett
Angi feltene og en tydelig samtykketekst.
Publiser
Nye skjemaer starter som utkast; offentlige ruter returnerer 404 frem til publisering.
Integrer
Bruk innbyggingskoden eller kall de to offentlige endepunktene nedenfor.
Bruk ditt eget HTML-skjema.
Direkte innsending støttes. Opprett og publiser et skjema i smartest.email for å definere felter og samtykketekst, og bruk deretter skjema-ID-en i det eksisterende nettstedsskjemaet. Du kan velge innebygd skjematype uten å installere modulen.
Nettstedet ditt kan sende med JavaScript fetch(), eller din egen server kan videresende påmeldingen som JSON. Det offentlige endepunktet trenger ingen API-nøkkel, tilgangstoken eller innbyggingsskript fra smartest.email.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitErstatt FORM_ID med UUID-en til det publiserte skjemaet. Send Content-Type: application/json med innholdet nedenfor.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}Sett consent ut fra den besøkendes uttrykkelige valg, og vis skjemaets samtykketekst og personverninformasjon. Behold consent på øverste nivå; plasser konfigurerte kontaktfelter inni data. Ta med alle obligatoriske felter i det publiserte skjemaet.
En vanlig HTML-skjemahandling trenger en adapter
Endepunktet godtar bare JSON. Et vanlig <form method="post" action="…"> sender URL-kodede data eller multipart-data og mottar 415 JSON body required . Bruk JavaScript-eksempelet for nettleseren nedenfor, eller send til din egen server og la den sende JSON til smartest.email.
Ved å hente den offentlige konfigurasjonen holdes etiketter og validering i samsvar med det publiserte skjemaet. Det er ikke nødvendig ved hver innsending. Integrasjonen håndterer sin egen suksessmelding eller omdirigering; dette endepunktet svarer alltid med JSON.
Vis feltene du har publisert.
Dette offentlige endepunktet trenger ikke tilgangstoken. Hent det når skjemaet vises, og bruk de returnerte feltnavnene, samtykketeksten og personvern-URL-en i ditt eget grensesnitt.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Returnerer 200 med trygge visningsdata for et aktivt skjema. Hver vellykket henting øker visningstallet; unngå gjentatt polling.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsFerdig skript for innebygd modul eller popup-modul. Bruk den nøyaktige skript-URL-en fra Installer hvis du ikke trenger et eget grensesnitt.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingDriftet påmeldingsside for et aktivt skjema.
{
"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 inneholde flere konfigurerte felter, valg og valideringsregler. successAction beskriver virkemåten til den ferdige modulen; direkte innsending returnerer fortsatt det generelle JSON-svaret nedenfor. Skriptet og den driftede siden returnerer 404 for utkast samt upubliserte, ugyldige eller ukjente skjemaer.
Send samtykke sammen med dataene.
Send JSON etter at besøkende uttrykkelig velger å motta markedsførings-e-post. Samtykkeflagget hører hjemme på øverste nivå; ikke legg consent inni data.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitIngen tilgangstoken. Send Content-Type: application/json og {data:{email:...},consent:true}. Returnerer samme generelle suksessvar for nye og eksisterende 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>Erstatt FORM_ID med skjemaets UUID, og angi reservelenken /privacy til din egen informasjon hvis skjemaet ikke har konfigurert privacyUrl. Eksemplet håndterer de to obligatoriske feltene; vis og send eventuelle andre obligatoriske felter fra den publiserte konfigurasjonen.
Godkjent svar
{"success":true,"message":"Thank you for subscribing."}Svaret oppgir bevisst ikke om en adresse finnes fra før. Eksisterende påmeldte og avmeldte kontakter beholder gjeldende status; bare en ny godkjent adresse legger til en abonnent og en samtykkeoppføring.
Send bare navn som finnes i den publiserte fields listen. Obligatoriske felter må oppgis. For ekstra felter sendes avkrysningsverdier som boolske verdier, tall som numeriske strenger, datoer som YYYY-MM-DD, og valg- eller radioknappverdier nøyaktig som oppført i options. API-et validerer dataene på nytt på serveren.
Den valgfrie egenskapen på øverste nivå website er en spamfelle. Utelat den eller la den være tom ved vanlig innsending. En verdi som ikke er tom returnerer det generelle suksessvaret uten å legge til en kontakt; det er ikke et felt for den besøkendes nettstedsadresse.
Håndter feil og trafikkgrenser.
Offentlige skjemaendepunkter tillater GET-, POST- og OPTIONS-forespørsler fra eksterne nettsteder med Content-Type- og Accept-hoder. Bruk credentials: omit i nettleserforespørsler; ingen kontoinformasjonskapsler, Authorization-hoder eller API-nøkler er nødvendige.
| Status | Betydning |
|---|---|
| 200 | Konfigurasjon eller godkjent innsending; en duplikatadresse får samme innsendingssvar. |
| 400 / 415 | Ugyldig JSON / forespørselen er ikke application/json. |
| 404 | Ukjent, utkast, upublisert eller ugyldig skjema. |
| 409 | Kontoen har nådd kontaktgrensen. |
| 413 / 422 | Innholdet overstiger 16 KiB / samtykke eller feltdata er ugyldig. |
| 429 | Frekvensgrensen er nådd; nettleserkode kan bruke retry_after i JSON-innholdet. Serverintegrasjoner kan også lese Retry-After. |
Feil bruker {"error":true,"message":"..."}; frekvensgrensefeil inkluderer også retry_after i sekunder. Skjemaer tillater opptil 30 forespørsler per IP-adresse per minutt, inkludert opptil 10 innsendinger. Nettstedets sikkerhetspolicy for innhold må tillate https://api.smartest.email i connect-src; den ferdige innbyggingen trenger den også i script-src.
Når din egen server videresender innsendinger, deler de serverens utgående IP-adresse ved begrensning av antall forespørsler.
Samtykke og levering
En ny godkjent påmelding oppretter en påmeldt kontakt og lagrer skjemaets samtykketekst, tidspunkt og oppgitte forespørselsopprinnelse. Ditt grensesnitt må vise skjemaets samtykketekst og personverninformasjon før besøkende sender inn. Registrert forespørselsopprinnelse er ikke identitetsbevis. Endepunktet bruker enkel påmelding; det sender ikke bekreftelses-e-post og bekrefter ikke eierskap til adressen.

