Liigu sisu juurde

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.

1

Loo

Määra väljad ja selge nõusolekutekst.

2

Avalda

Uued vormid on alguses mustandid; avalikud marsruudid tagastavad kuni avaldamiseni 404.

3

Ü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.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Asenda FORM_ID avaldatud vormi UUID-ga. Saada Content-Type: application/json koos alloleva sisuga.

JSON-päring · pärast külastaja nõusolekut
{
  "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.

GET
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.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.js

Valmis lehesisese või hüpikvidina skript. Kasuta paigaldamise vahekaardi täpset skripti URL-i, kui sa ei vaja kohandatud liidest.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landing

Aktiivse vormi majutatud liitumisleht.

GET /api/v1/public/forms/{FORM_ID} · vastuse näide
{
  "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.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Ilma juurdepääsutõendita. Saada Content-Type: application/json ja {data:{email:...},consent:true}. Tagastab uutele ja olemasolevatele aadressidele sama üldise eduvastuse.

HTML + brauseri JavaScript · e-posti ja nõusoleku vorm
<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

JSON
{"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.

OlekTähendus
200Seadistus või vastuvõetud esitamine; korduv aadress saab sama esitamisvastuse.
400 / 415Vigane JSON / päring pole application/json.
404Tundmatu, mustandina, avaldamata või kehtetu vorm.
409Konto kontaktipiirang on täis.
413 / 422Sisu ületab 16 KiB / nõusolek või väljaandmed on vigased.
429Pä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.