دليل المطور · نماذج الاشتراك
أنشئ تجربة الاشتراك الخاصة بك.
احتفظ بـ HTML والتنسيق وإطار موقعك الخاص. اربط نموذجك المخصص بنموذج smartest.email منشور عبر نقطة الاشتراك العامة.
يشمل هذا الدليل
إعدادات النماذج العامة والاشتراكات من أي أصل موقع
الموافقة والتحقق والاستجابات وحدود المعدل
استخدم الرابط الظاهر في نموذجك.
أنشئ نموذجًا في نماذج الاشتراك وأضف حقل بريد إلزاميًا ومربع موافقة إلزاميًا ثم انشره. تعرض علامة تبويب التثبيت الرابط الدقيق لنموذجك.
الرابط الأساسي
https://api.smartest.email/api/v1/public/forms/{FORM_ID}استخدم عنوان URL الظاهر في علامة التبويب «تثبيت» الخاصة بالنموذج. استبدل FORM_ID بمعرّف نموذجك المنشور في الأمثلة أدناه.
إنشاء
حدّد حقولك ونص موافقة واضحًا.
نشر
تبدأ النماذج الجديدة كمسودات؛ وتعيد المسارات العامة 404 حتى تُنشر.
تكامل
استخدم مقتطف التضمين أو استدعِ نقطتي الاتصال العامتين أدناه.
استخدم نموذج HTML الخاص بك.
الإرسال المباشر مدعوم. أنشئ نموذجًا وانشره في smartest.email لتحديد حقوله ونص الموافقة، ثم استخدم معرّف النموذج في نموذج موقعك الحالي. يمكنك اختيار نوع النموذج المضمن دون تثبيت الأداة.
يمكن لموقعك الإرسال باستخدام JavaScript fetch()، أو يمكن لخادمك إعادة توجيه الاشتراك بصيغة JSON. لا تحتاج نقطة الاتصال العامة إلى مفتاح API أو رمز وصول أو سكربت تضمين smartest.email.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitاستبدل FORM_ID بمعرّف UUID لنموذجك المنشور. أرسل Content-Type: application/json مع البيانات أدناه.
{
"data": {
"email": "visitor@example.com"
},
"consent": true
}اضبط consent وفق اختيار الزائر الصريح، واعرض نص موافقة النموذج وإشعار الخصوصية. احتفظ بـ consent في المستوى الأعلى، وضع حقول جهات الاتصال المضبوطة داخل data. أدرج كل حقل مطلوب في نموذجك المنشور.
يحتاج إرسال نموذج HTML عادي إلى وسيط تحويل
تقبل نقطة الاتصال JSON فقط. يرسل <form method="post" action="…"> العادي بيانات بترميز URL أو multipart ويتلقى 415 JSON body required. استخدم مثال JavaScript للمتصفح أدناه، أو أرسل إلى خادمك واجعله يرسل JSON إلى smartest.email.
يضمن جلب الإعدادات العامة تطابق التسميات والتحقق مع النموذج المنشور. وليس ذلك شرطًا لكل إرسال. يتولى تكاملك رسالة النجاح أو إعادة التوجيه؛ وتستجيب نقطة الاتصال هذه دائمًا بصيغة JSON.
اعرض الحقول التي نشرتها.
لا تحتاج نقطة الاتصال العامة هذه إلى رمز وصول. اجلبها عند عرض النموذج، ثم استخدم أسماء الحقول ونص الموافقة ورابط الخصوصية في واجهتك المخصصة.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}تعيد 200 مع بيانات عرض آمنة لنموذج نشط. يزيد كل جلب ناجح عدد المشاهدات؛ تجنّب الاستطلاع المتكرر.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.jsسكربت جاهز لأداة داخل الصفحة أو منبثقة. استخدم رابط السكربت الدقيق من التثبيت إذا لم تكن تحتاج إلى واجهة مخصصة.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landingصفحة اشتراك مستضافة لنموذج نشط.
{
"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"
}قد تتضمن الاستجابة حقولًا وخيارات وقواعد تحقق إضافية مضبوطة. successAction يصف سلوك الأداة الجاهزة؛ أما الإرسال المباشر فيعيد استجابة JSON العامة أدناه. يعيد السكربت والصفحة المستضافة 404 للنماذج المسودة أو غير المنشورة أو غير الصالحة أو غير المعروفة.
أرسل الموافقة مع البيانات.
أرسل JSON بعد أن يختار الزائر صراحة تلقي البريد التسويقي. ضع علامة الموافقة في المستوى الأعلى، ولا تضع consent داخل data.
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submitلا يلزم رمز وصول. أرسل Content-Type: application/json و{data:{email:...},consent:true}. تعاد استجابة النجاح العامة نفسها للعناوين الجديدة والموجودة.
<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>استبدل FORM_ID بمعرّف UUID لنموذجك، واضبط رابط /privacy الاحتياطي على إشعارك الخاص إذا لم يُضبط للنموذج privacyUrl. يعالج هذا المثال الحقلين المطلوبين؛ اعرض وأرسل أي حقول إلزامية إضافية من إعداداتك المنشورة.
استجابة القبول
{"success":true,"message":"Thank you for subscribing."}لا توضّح الاستجابة عمدًا ما إذا كان العنوان موجودًا بالفعل. تحتفظ جهات الاتصال المشتركة والتي ألغت الاشتراك بحالتها الحالية؛ ويضيف العنوان الجديد المقبول فقط مشتركًا وسجل موافقة.
أرسل فقط الأسماء الموجودة في مصفوفة fields المنشورة. يجب توفير الحقول المطلوبة. للحقول الإضافية، أرسل قيم مربعات الاختيار كقيم منطقية، والأرقام كسلاسل رقمية، والتواريخ بتنسيق YYYY-MM-DD، وقيم القوائم أو أزرار الاختيار تمامًا كما وردت في options. تعيد الواجهة التحقق من البيانات على الخادم.
الخاصية الاختيارية في المستوى الأعلى website هي حقل طُعم لمكافحة الرسائل المزعجة. احذفها أو اتركها فارغة للإرسال العادي. تعيد القيمة غير الفارغة استجابة نجاح عامة دون إضافة جهة اتصال؛ وليست حقلًا لرابط موقع الزائر.
تعامل مع الإخفاقات وحدود حركة الطلبات.
تسمح نقاط النماذج العامة بطلبات GET وPOST وOPTIONS من مواقع خارجية عبر أصول مختلفة مع ترويستي Content-Type وAccept. استخدم credentials: omit في طلبات المتصفح؛ لا تحتاج إلى ملفات تعريف ارتباط للحساب أو ترويسة Authorization أو مفتاح API.
| الحالة | المعنى |
|---|---|
| 200 | إعدادات أو إرسال مقبول؛ ويتلقى العنوان المكرر استجابة الإرسال نفسها. |
| 400 / 415 | JSON غير صالح / الطلب ليس application/json. |
| 404 | نموذج غير معروف أو مسودة أو غير منشور أو غير صالح. |
| 409 | بلغ الحساب الحد الأقصى لجهات الاتصال. |
| 413 / 422 | يتجاوز المحتوى 16 KiB / الموافقة أو بيانات الحقول غير صالحة. |
| 429 | تم بلوغ حد المعدل؛ يمكن لكود المتصفح استخدام retry_after في محتوى JSON. ويمكن لتكاملات الخادم أيضًا قراءة Retry-After. |
تستخدم الأخطاء {"error":true,"message":"..."}؛ وتتضمن أخطاء حد المعدل أيضًا retry_after بالثواني. تسمح النماذج بما يصل إلى 30 طلبًا لكل عنوان IP في الدقيقة، منها 10 عمليات إرسال كحد أقصى. يجب أن تسمح سياسة أمان المحتوى في موقعك بالوصول إلى https://api.smartest.email في connect-src؛ ويحتاج التضمين الجاهز أيضًا إلى السماح به في script-src.
عندما يعيد خادمك توجيه عمليات الإرسال، فإنها تشترك في عنوان IP الصادر لذلك الخادم عند تطبيق حدود معدل الطلبات.
الموافقة والتسليم
يؤدي الاشتراك الجديد المقبول إلى إنشاء جهة اتصال مشتركة وحفظ نص موافقة النموذج والوقت ومصدر الطلب المقدم. يجب أن تعرض واجهتك نص الموافقة وإشعار الخصوصية قبل الإرسال. مصدر الطلب المسجل ليس دليل هوية. تستخدم هذه النقطة موافقة اشتراك أحادية؛ ولا ترسل بريد تأكيد ولا تتحقق من ملكية العنوان.

