Arendaja juhend · Liitumisvormid
Loo oma liitumiskogemus.
Säilita oma HTML, stiil ja veebiraamistik. Ühenda kohandatud vorm avaldatud smartest.emaili vormiga selle avaliku liitumise lõpp-punkti kaudu.
See juhend käsitleb
Avalik vormiseadistus ja liitumine mis tahes veebilehelt
Nõusolek, valideerimine, vastused ja päringupiirangud
Kasuta oma vormi URL-i.
Loo jaotises Liitumisvormid vorm, lisa kohustuslik e-posti väli ja nõusoleku märkeruut ning avalda see. Paigaldamise vahekaardil näed vormi täpset URL-i.
Baas-URL
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Kasuta vormi vahekaardil Paigaldamine kuvatud URL-i. Asenda allolevates näidetes FORM_ID avaldatud vormi ID-ga.
Loo
Määra väljad ja selge nõusolekutekst.
Avalda
Uued vormid on alguses mustandid; avalikud marsruudid tagastavad kuni avaldamiseni 404.
Ühenda
Kasuta manustamiskoodi või kutsu allolevat kahte avalikku lõpp-punkti.
Kasuta oma HTML-vormi.
Otse esitamine on toetatud. Loo ja avalda smartest.emailis vorm, et määrata väljad ja nõusoleku tekst, ning kasuta selle vormi ID-d oma olemasolevas veebivormis. Võid valida manustatud vormi tüübi vidinat paigaldamata.
Sinu veebileht saab esitada JavaScripti abil fetch(), või sinu server saab liitumise JSON-ina edasi saata. Avalik lõpp-punkt ei vaja API võtit, juurdepääsutõendit ega smartest.emaili manustamisskripti.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitAsenda FORM_ID avaldatud vormi UUID-ga. Saada Content-Type: application/json koos alloleva sisuga.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}Määra consent külastaja selgesõnalise valiku põhjal ning näita vormi nõusolekuteksti ja privaatsusteavet. Hoia consent kõrgeimal tasemel; paiguta seadistatud kontaktiväljad sisse data. Kaasa iga avaldatud vormi kohustuslik väli.
Tavaline HTML-vormi toiming vajab adapterit
Lõpp-punkt võtab vastu ainult JSON-i. Tavaline <form method="post" action="…"> saadab URL-kodeeritud või multipart-andmeid ja saab vastuseks 415 JSON body required. Kasuta allolevat brauseri JavaScripti näidet, või postita oma serverisse ja lase sellel JSON smartest.emailile saata.
Laadides avaliku seadistuse hoiad sildid ja valideerimise avaldatud vormiga kooskõlas. See pole iga esitamise eeltingimus. Integratsioon haldab oma õnnestumisteadet või ümbersuunamist; see lõpp-punkt vastab alati JSON-iga.
Kuva avaldatud väljad.
See avalik lõpp-punkt ei vaja juurdepääsutõendit. Laadi see vormi kuvamisel ning kasuta tagastatud väljanimesid, nõusolekuteksti ja privaatsus-URL-i oma liideses.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Tagastab 200 koos aktiivse vormi turvaliste kuvaandmetega. Iga õnnestunud laadimine suurendab vaatamiste arvu; väldi korduvat pärimist.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsValmis lehesisese või hüpikvidina skript. Kasuta paigaldamise vahekaardi täpset skripti URL-i, kui sa ei vaja kohandatud liidest.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingAktiivse vormi majutatud liitumisleht.
{
"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"
}Vastus võib sisaldada täiendavaid seadistatud välju, valikuid ja valideerimisreegleid. successAction kirjeldab valmisvidina käitumist; otse esitamine tagastab siiski alloleva üldise JSON-vastuse. Skript ja majutatud leht tagastavad mustandite, avaldamata, kehtetute või tundmatute vormide puhul 404.
Saada nõusolek koos andmetega.
Postita JSON pärast külastaja selgesõnalist nõusolekut turunduskirjade saamiseks. Nõusoleku lipp kuulub kõrgeimale tasemele; ära pane consent-välja data sisse.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitIlma juurdepääsutõendita. Saada Content-Type: application/json ja {data:{email:...},consent:true}. Tagastab uutele ja olemasolevatele aadressidele sama üldise eduvastuse.
<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>Asenda FORM_ID oma vormi UUID-ga ja määra varuvariant /privacy link oma teabele, kui vormis pole seadistatud privacyUrl. See näide käsitleb kahte kohustuslikku välja; kuva ja saada kõik avaldatud seadistuse täiendavad kohustuslikud väljad.
Vastuvõtmise vastus
{"success":true,"message":"Thank you for subscribing."}Vastus ei ütle teadlikult, kas aadress on juba olemas. Olemasolevad liitunud ja loobunud kontaktid säilitavad oma oleku; ainult uus vastuvõetud aadress lisab tellija ja nõusolekukirje.
Saada ainult nimed, mis esinevad avaldatud fields massiivis. Kohustuslikud väljad tuleb esitada. Lisaväljade puhul saada märkeruudud tõeväärtustena, arvud arvuliste stringidena, kuupäevad kujul YYYY-MM-DD, ning select- või radio-väärtused täpselt nii, nagu on loetletud options. API valideerib andmed serveris uuesti.
Valikuline kõrgeima taseme website omadus on rämpspostilõks. Tavalise esitamise korral jäta see välja või tühjaks. Mittetühi väärtus tagastab üldise eduvastuse kontakti lisamata; see pole külastaja veebilehe URL-i väli.
Käsitle tõrkeid ja liikluspiiranguid.
Avalikud vormi lõpp-punktid lubavad välistelt veebilehtedelt päritoluüleseid GET-, POST- ja OPTIONS-päringuid koos Content-Type- ja Accept-päistega. Kasuta brauseripäringutes credentials: omit; konto küpsiseid, Authorization-päist ega API võtit pole vaja.
| Olek | Tähendus |
|---|---|
| 200 | Seadistus või vastuvõetud esitamine; korduv aadress saab sama esitamisvastuse. |
| 400 / 415 | Vigane JSON / päring pole application/json. |
| 404 | Tundmatu, mustandina, avaldamata või kehtetu vorm. |
| 409 | Konto kontaktipiirang on täis. |
| 413 / 422 | Sisu ületab 16 KiB / nõusolek või väljaandmed on vigased. |
| 429 | Päringupiirang täis; brauserikood saab kasutada retry_after JSON-i sisus. Serveri integratsioonid saavad lugeda ka Retry-After. |
Vead kasutavad {"error":true,"message":"..."}; päringupiirangu vead sisaldavad ka retry_after sekundites. Vormid lubavad kuni 30 päringut IP-aadressi kohta minutis, sealhulgas kuni 10 esitamist. Sinu veebisaidi sisuturbepoliitika peab lubama https://api.smartest.email sees connect-src; valmis manustus vajab seda ka sees script-src.
Kui sinu server edastab vormiesitusi, jagavad need päringupiirangu arvestamisel selle serveri väljuvat IP-aadressi.
Nõusolek ja kohaletoimetamine
Uus vastuvõetud liitumine loob tellimusega kontakti ning salvestab vormi nõusolekuteksti, aja ja esitatud päringu päritolu. Sinu liides peab enne esitamist kuvama vormi nõusolekuteksti ja privaatsusteabe. Talletatud päringu päritolu ei tõenda isikut. See lõpp-punkt kasutab ühekordset nõusolekut; see ei saada kinnituskirja ega kontrolli aadressi omandit.

