Kehittäjän opas · Liittymislomakkeet
Luo oma liittymiskokemuksesi.
Säilytä oma HTML, tyylit ja verkkosivuston kehys. Yhdistä oma lomakkeesi julkaistuun smartest.email-lomakkeeseen sen julkisen liittymispäätepisteen kautta.
Tämä opas käsittelee
Julkinen lomakemääritys ja liittymiset mistä tahansa verkkosivuston alkuperästä
Suostumus, validointi, vastaukset ja pyyntörajat
Käytä lomakkeesi URL-osoitetta.
Luo lomake Liittymislomakkeet-osiossa, lisää pakollinen sähköpostikenttä ja pakollinen suostumusvalintaruutu ja julkaise lomake. Asennus-välilehti näyttää lomakkeen tarkan URL-osoitteen.
Perus-URL
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Käytä lomakkeen Asenna-välilehdellä näkyvää URL-osoitetta. Korvaa alla olevissa esimerkeissä FORM_ID julkaistun lomakkeen tunnisteella.
Luo
Määritä kentät ja selkeä suostumusteksti.
Julkaise
Uudet lomakkeet alkavat luonnoksina; julkiset reitit palauttavat 404-virheen julkaisemiseen asti.
Integroi
Käytä upotuskoodia tai kutsu alla olevia kahta julkista päätepistettä.
Käytä omaa HTML-lomakettasi.
Suora lähetys on tuettu. Luo ja julkaise lomake smartest.emailissä kenttien ja suostumustekstin määrittämiseksi ja käytä sitten sen lomaketunnusta nykyisessä sivustolomakkeessasi. Voit valita upotetun lomaketyypin asentamatta widgettiä.
Sivustosi voi lähettää JavaScriptillä fetch(), tai oma palvelimesi voi välittää liittymisen JSON-muodossa. Julkinen päätepiste ei tarvitse API-avainta, käyttöoikeustunnusta tai smartest.emailin upotusskriptiä.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitKorvaa FORM_ID julkaistun lomakkeesi UUID:llä. Lähetä Content-Type: application/json alla olevan sisällön kanssa.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}Aseta consent kävijän nimenomaisen valinnan perusteella ja näytä lomakkeen suostumusteksti ja tietosuojailmoitus. Pidä consent ylimmällä tasolla; sijoita määritetyt yhteystietokentät kohteeseen data. Sisällytä julkaistun lomakkeesi kaikki pakolliset kentät.
Tavallinen HTML-lomakkeen action tarvitsee sovittimen
Päätepiste hyväksyy vain JSON-muodon. Tavallinen <form method="post" action="…"> lähettää URL-koodattua tai multipart-dataa ja saa 415 JSON body required . Käytä alla olevaa selaimen JavaScript-esimerkkiä, tai lähetä omalle palvelimellesi ja anna sen lähettää JSON-data smartest.emailiin.
Noutamalla julkisen määrityksen pidät kenttien nimet ja validoinnin julkaistun lomakkeen mukaisina. Sitä ei edellytetä jokaisella lähetyksellä. Integraatiosi käsittelee oman onnistumisviestinsä tai uudelleenohjauksensa; tämä päätepiste vastaa aina JSON-muodossa.
Näytä julkaisemasi kentät.
Tämä julkinen päätepiste ei tarvitse käyttöoikeustunnusta. Nouda se lomaketta näytettäessä ja käytä palautettuja kenttänimiä, suostumustekstiä ja tietosuojan URL-osoitetta omassa käyttöliittymässäsi.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}Palauttaa 200-vastauksen ja turvalliset esitystiedot aktiiviselle lomakkeelle. Jokainen onnistunut haku kasvattaa katselukertojen määrää; vältä jatkuvaa kyselyä.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsValmis upotettavan tai ponnahdusikkunawidgetin skripti. Käytä Asennus-osion tarkkaa skriptin URL-osoitetta, jos et tarvitse omaa käyttöliittymää.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingIsännöity liittymissivu aktiiviselle lomakkeelle.
{
"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"
}Vastaus voi sisältää lisää määritettyjä kenttiä, vaihtoehtoja ja validointisääntöjä. successAction kuvaa valmiin widgetin toimintaa; suora lähetys palauttaa edelleen alla olevan yleisen JSON-vastauksen. Skripti ja isännöity sivu palauttavat 404-virheen luonnoksille sekä julkaisemattomille, virheellisille tai tuntemattomille lomakkeille.
Lähetä suostumus tietojen mukana.
Lähetä JSON vasta, kun kävijä on nimenomaisesti valinnut markkinointisähköpostien vastaanottamisen. Suostumuslippu kuuluu ylimmälle tasolle; älä sijoita consent-kenttää data-kentän sisään.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitEi käyttöoikeustunnusta. Lähetä Content-Type: application/json ja {data:{email:...},consent:true}. Palauttaa saman yleisen onnistumisvastauksen uusille ja olemassa oleville osoitteille.
<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>Korvaa FORM_ID lomakkeesi UUID:llä ja aseta varalinkki /privacy omaan ilmoitukseesi, jos lomakkeella ei ole määritettyä privacyUrl. Tämä esimerkki käsittelee kahta pakollista kenttää; näytä ja lähetä myös muut julkaistun määrityksesi pakolliset kentät.
Hyväksytty vastaus
{"success":true,"message":"Thank you for subscribing."}Vastaus ei tarkoituksella kerro, onko osoite jo olemassa. Nykyiset tilanneet ja tilauksen peruneet yhteystiedot säilyttävät tilansa; vain uusi hyväksytty osoite lisää tilaajan ja suostumustietueen.
Lähetä vain nimiä, jotka ovat julkaistussa fields taulukossa. Pakolliset kentät on annettava. Lisäkenttien valintaruutuarvot lähetetään totuusarvoina, numerot numeerisina merkkijonoina ja päivämäärät muodossa YYYY-MM-DD, ja valinta- tai valintanappiarvot täsmälleen luettelon mukaisesti kohdassa options. API validoi tiedot uudelleen palvelimella.
Valinnainen ylimmän tason website ominaisuus on roskapostiansa. Jätä se pois tai tyhjäksi tavallisessa lähetyksessä. Muu kuin tyhjä arvo palauttaa yleisen onnistumisvastauksen lisäämättä yhteystietoa; kenttä ei ole tarkoitettu kävijän verkkosivuston URL-osoitteelle.
Käsittele virheet ja liikenteen rajat.
Julkiset lomakepäätepisteet sallivat ulkoisilta sivustoilta tulevat eri alkuperien GET-, POST- ja OPTIONS-pyynnöt Content-Type- ja Accept-otsakkeilla. Käytä selainpyynnöissä credentials: omit; tilievästeitä, Authorization-otsaketta tai API-avainta ei tarvita.
| Tila | Merkitys |
|---|---|
| 200 | Määritys tai hyväksytty lähetys; jo olemassa oleva osoite saa saman lähetysvastauksen. |
| 400 / 415 | Virheellinen JSON / pyyntö ei ole application/json. |
| 404 | Tuntematon, luonnostilassa oleva, julkaisematon tai virheellinen lomake. |
| 409 | Tili on saavuttanut yhteystietorajansa. |
| 413 / 422 | Sisältö ylittää 16 KiB / suostumus tai kenttätiedot ovat virheellisiä. |
| 429 | Pyyntöraja saavutettu; selainkoodi voi käyttää retry_after JSON-sisällössä. Palvelinintegraatiot voivat myös lukea Retry-After. |
Virheet käyttävät {"error":true,"message":"..."}; pyyntörajojen virheet sisältävät myös retry_after sekunteina. Lomakkeille sallitaan enintään 30 pyyntöä IP-osoitetta kohti minuutissa, joista enintään 10 on lähetyksiä. Sivustosi sisällön suojauskäytännön on sallittava https://api.smartest.email kohdassa connect-src; valmis upotus tarvitsee sen myös kohdassa script-src.
Kun oma palvelimesi välittää lähetyksiä, ne jakavat palvelimen lähtevän IP-osoitteen pyyntörajoitusten laskennassa.
Suostumus ja toimitus
Uusi hyväksytty liittyminen luo tilanneen yhteystiedon ja tallentaa lomakkeen suostumustekstin, ajan ja annetun pyynnön alkuperän. Oman käyttöliittymäsi on näytettävä lomakkeen suostumusteksti ja tietosuojailmoitus ennen lähetystä. Tallennettu pyynnön alkuperä ei todista henkilöllisyyttä. Päätepiste käyttää yksivaiheista liittymistä; se ei lähetä vahvistussähköpostia eikä varmista osoitteen omistusta.

