واجهة برمجة تطبيقات قوالب البريد الإلكتر الإلكتروني

تدير واجهة برمجة تطبيقات قوالب البريد الإلكتروني (Email Templates API) قوالب البريد الإلكتروني القابلة لإعادة الاستخدام وراء الإعدادات المسبقة للبريد الإلكتروني للتطبيق — وهي نفس القوالب التي تنشئها في محرر البريد الإلكتروني في لوحة التحكم (Control Panel). يخزن كل قالب مواضيع خاصة بكل لغة، ومعلومات المرسل، ومحتوى المحرر، ويتم تحديده بواسطة رمز إعداد البريد الإلكتروني المسبق المتصل به. استخدم هذا الرمز لإرسال القالب عبر Notify (حمولة البريد الإلكتروني email_template) أو نقطة إرسال بريد إلكتروني في Customer Journey Send email point.

عنوان URL الأساسي

https://rpc-api.svc-nue.pushwoosh.com

يتم تقديم جميع نقاط النهاية عبر HTTPS. تستخدم الطلبات والاستجابات application/json ما لم يُذكر خلاف ذلك.

المصادقة

يجب أن يتضمن كل طلب ترويسة Authorization مع رمز واجهة برمجة تطبيقات الخادم (Server API token) الخاص بك:

Authorization: Api YOUR_API_TOKEN

الاصطلاحات

تسمية الحقول: تقبل أجسام الطلبات ومعلمات الاستعلام/المسار lowerCamelCase (على سبيل المثال، previewSettings، searchByLabel، includeHtml) — يقوم الخادم بفك ترميز أي من الحالتين. يتم دائمًا ترميز الاستجابات باستخدام أسماء حقول proto، في snake_case (per_page، email_template، sender_info، preview_settings، وهكذا). تستخدم أمثلة الاستجابة ومرجع الكائن أدناه هذه الحالة.
code: تحمل كل استجابة قالب رمز إعداد البريد الإلكتروني المسبق المتصل به، وليس معرف قالب داخلي. مرر هذا الرمز نفسه إلى Get و Update و Delete وإلى واجهات برمجة تطبيقات المراسلة/الرحلة المذكورة أعلاه.
الحقول غير المعبأة: تتضمن الاستجابات جميع الحقول، حتى عندما تكون فارغة أو قيمتها صفر.

استجابات الخطأ

حالة HTTP	المعنى
`400 Bad Request`	وسيطة غير صالحة — حقل مطلوب مفقود أو مشوه، أو فشل شرط مسبق (على سبيل المثال، حذف قالب لا يزال مستخدمًا في رحلة).
`401 Unauthorized`	ترويسة `Authorization` مفقودة أو غير صالحة.
`403 Forbidden`	التطبيق أو الإعداد المسبق لا ينتمي إلى حساب المتصل.
`404 Not Found`	لم يتم العثور على القالب أو الإعداد المسبق أو التطبيق.
`500 Internal Server Error`	فشل غير متوقع من جانب الخادم.

نقاط النهاية

الطريقة	المسار	الوصف
`POST`	`/api/email_templates`	إنشاء قالب بريد إلكتروني جديد
`GET`	`/api/email_templates`	إدراج قوالب البريد الإلكتروني لتطبيق ما
`GET`	`/api/email_templates/{code}`	الحصول على قالب بريد إلكتروني واحد
`PUT`	`/api/email_templates/{code}`	تحديث قالب بريد إلكتروني
`DELETE`	`/api/email_templates/{code}`	حذف قالب بريد إلكتروني
`POST`	`/api/email_templates:clone`	استنساخ قالب بريد إلكتروني في تطبيق

إنشاء

ينشئ قالب بريد إلكتروني جديدًا — محتوى المحرر الخاص به بالإضافة إلى إعداد بريد إلكتروني مسبق متصل — في تطبيق، ويعيد رمز القالب الذي تم إنشاؤه.

POST /api/email_templates

جسم الطلب

المعلمة	النوع	مطلوب	الوصف
`application`	string	نعم	رمز تطبيق Pushwoosh لإنشاء القالب فيه.
`name`	string	نعم	اسم القالب، 1–255 حرفًا.
`content`	object	نعم	كائن محتوى البريد الإلكتروني.
`label`	string	لا	تسمية نصية حرة، تصل إلى 255 حرفًا.
`categories`	array of strings	لا	أسماء الفئات لوضع علامات على القالب بها.
`previewSettings`	object	لا	إعدادات معاينة المحرر العشوائية، يتم تخزينها وإعادتها كما هي.
`system`	boolean	لا	يحدد القالب كقالب نظام — ميزة داخلية، على سبيل المثال، جزء كتلة متزامنة. يتم إخفاء قوالب النظام من `List` (انظر الملاحظة أدناه)، ولكنها تظل قابلة للوصول عن طريق الرمز. القيمة الافتراضية هي `false`.

مثال على الطلب

{
  "application": "XXXXX-XXXXX",
  "name": "Welcome email",
  "label": "onboarding",
  "categories": ["lifecycle"],
  "content": {
    "senderInfo": {
      "from": { "email": "hello@acme.com", "name": "Acme" },
      "replyTo": { "email": "support@acme.com", "name": "Acme Support" }
    },
    "subject": { "en": "Welcome to Acme!", "default": "Welcome to Acme!" },
    "pushwoosh": {
      "html": "<html><body>Welcome, {name|string|there}!</body></html>",
      "localizationData": { "default": { "name": "there" } }
    }
  }
}

الاستجابة

يعيد { "email_template": { ... } } — كائن قالب البريد الإلكتروني الذي تم إنشاؤه، ولكن بدون content (لا تعيد نقطة النهاية هذه المحتوى). استدعِ Get بالرمز code المُعاد إذا كنت بحاجة إلى قراءة المحتوى مرة أخرى.

إدراج

يدرج قوالب البريد الإلكتروني للتطبيق — البيانات الوصفية فقط، بدون محتوى — مع ترقيم الصفحات والترتيب والتصفية حسب الاسم أو التسمية أو الفئة.

GET /api/email_templates

معلمات الاستعلام

المعلمة	النوع	مطلوب	الوصف
`application`	string	نعم	رمز التطبيق لإدراج القوالب له.
`orderBy`	string	لا	`NAME` (افتراضي)، `CREATED`، أو `UPDATED`.
`orderDirection`	string	لا	`ASC` (افتراضي) أو `DESC`.
`page`	integer	لا	فهرس الصفحة المستند إلى الصفر.
`perPage`	integer	لا	حجم الصفحة. القيمة الافتراضية هي `100` عند الحذف أو `0`. لا تفرض نقطة النهاية هذه حدًا أقصى صريحًا.
`searchByName`	string	لا	تطابق سلسلة فرعية (`like %value%`) مع اسم القالب أو رمزه — أي تطابق يكفي.
`searchByLabel`	string	لا	تطابق سلسلة فرعية على التسمية (`like %label%`)، أو تطابق تام عندما تكون `strictSearchByLabel` هي `true`.
`strictSearchByLabel`	boolean	لا	استخدم التطابق التام بدلاً من السلسلة الفرعية لـ `searchByLabel`.
`searchByCategory`	array of strings	لا	كرر المعلمة للتصفية حسب أي من الفئات المتعددة، على سبيل المثال `?searchByCategory=lifecycle&searchByCategory=promo`.

الاستجابة

الحقل	النوع	الوصف
`email_templates`	array of objects	الصفحة الحالية من كائنات قالب البريد الإلكتروني. `content` هو `null` في كل عنصر.
`page`	integer	فهرس الصفحة المُعاد.
`per_page`	integer	حجم الصفحة المستخدم لهذه الاستجابة.
`total`	integer	العدد الإجمالي للقوالب التي تطابق عوامل التصفية، عبر جميع الصفحات.

مثال على الاستجابة

{
  "email_templates": [
    { "code": "AAAAA-BBBBB", "name": "Welcome email", "label": "onboarding", "categories": ["lifecycle"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

الحصول على

يعيد قالب بريد إلكتروني واحدًا برمزه، بما في ذلك معلومات المرسل، والمواضيع الخاصة بكل لغة، ومحتوى المحرر الكامل.

GET /api/email_templates/{code}

معلمات المسار

المعلمة	النوع	الوصف
`code`	string	رمز القالب (رمز إعداد البريد الإلكتروني المسبق المتصل به).

معلمات الاستعلام

المعلمة	النوع	مطلوب	الوصف
`includeHtml`	boolean	لا	ما إذا كان سيتم إرجاع `html` المعروضة إلى جانب محتوى المحرر. القيمة الافتراضية هي `true`. اضبطها على `false` لتخطيه — فهو عادة ما يكون أكثر من نصف الحمولة، ومحتوى المحرر يصف القالب بالفعل.

الاستجابة

يعيد { "email_template": { ... } }، كائن قالب البريد الإلكتروني الكامل.

تحديث

يحدّث قالب بريد إلكتروني موجودًا برمزه، مع الكتابة فوق الحقول المقدمة.

PUT /api/email_templates/{code}

معلمات المسار

المعلمة	النوع	الوصف
`code`	string	رمز القالب المراد تحديثه.

جسم الطلب

المعلمة	النوع	مطلوب	الوصف
`name`	string	لا	اسم جديد، 1–255 حرفًا. احذفه للحفاظ على الاسم الحالي.
`content`	object	لا	كائن محتوى بريد إلكتروني جديد، يحل محل المحتوى المخزن بالكامل. احذفه لترك المحتوى دون تغيير.
`label`	string	لا	تسمية جديدة. يتم الكتابة فوقها دائمًا — احذفها أو أرسل `""` لمسحها.
`categories`	array of strings	لا	مجموعة كاملة جديدة من أسماء الفئات. احذفها لترك الفئات دون تغيير؛ أرسل `[]` لمسحها.
`previewSettings`	object	لا	إعدادات معاينة جديدة. احذفها لتركها دون تغيير.

مثال على الطلب

{
  "name": "Welcome email v2",
  "label": "onboarding",
  "content": {
    "senderInfo": { "from": { "email": "hello@acme.com", "name": "Acme" } },
    "subject": { "default": "Welcome to Acme — updated!" },
    "pushwoosh": {
      "html": "<html>...</html>",
      "localizationData": {}
    }
  }
}

الاستجابة

يعيد { "email_template": { ... } } — كائن قالب البريد الإلكتروني المحدث، أيضًا بدون content. استدعِ Get إذا كنت بحاجة إلى قراءة المحتوى مرة أخرى.

حذف

يحذف قالب بريد إلكتروني والإعداد المسبق المتصل به برمزه، مع إزالة المحتوى المخزن.

DELETE /api/email_templates/{code}

معلمات المسار

المعلمة	النوع	الوصف
`code`	string	رمز القالب المراد حذفه.

الاستجابة

كائن فارغ عند النجاح: {}.

استنساخ

يستنسخ قالب بريد إلكتروني — محتواه والإعداد المسبق الخاص به — في تطبيق وجهة، اختياريًا تحت اسم جديد.

POST /api/email_templates:clone

جسم الطلب

المعلمة	النوع	مطلوب	الوصف
`emailPresetCode`	string	نعم	`code` القالب (كما هو مُعاد بواسطة `Create`، `Get`، `List`، أو `Update`) المراد استنساخه. تمت تسميته `emailPresetCode` هنا لأنه رمز إعداد البريد الإلكتروني المسبق المتصل — انظر الاصطلاحات.
`application`	string	نعم	رمز تطبيق الوجهة. يمكن أن يكون نفس التطبيق، أو تطبيقًا مختلفًا يملكه نفس الحساب.
`name`	string	لا	اسم للنسخة المستنسخة، 1–255 حرفًا. القيمة الافتراضية هي اسم القالب المصدر.

مثال على الطلب

{
  "emailPresetCode": "AAAAA-BBBBB",
  "application": "YYYYY-YYYYY",
  "name": "Welcome email (copy)"
}

الاستجابة

الحقل	النوع	الوصف
`email_preset_code`	string	`code` القالب الجديد — نفس المعرف الذي تستدعيه `Get`/`Update`/`Delete` بـ `code`.

مرجع الكائن

تتطابق أسماء الحقول أدناه مع ما تعيده Get و List و Update و Create بالفعل — أسماء حقول proto snake_case (انظر الاصطلاحات). عندما ترسل هذه الهياكل نفسها مرة أخرى في جسم الطلب (Create، Update)، يعمل النموذج lowerCamelCase المستخدم في أمثلة الطلب أعلاه أيضًا؛ يقبل الخادم أيًا من الحالتين عند الإدخال.

كائن قالب البريد الإلكتروني

الحقل	النوع	الوصف
`code`	string	رمز إعداد البريد الإلكتروني المسبق المتصل. يحدد هذا القالب في كل مكان آخر في واجهة برمجة التطبيقات.
`name`	string	اسم القالب.
`label`	string	تسمية نصية حرة.
`categories`	array of strings	أسماء الفئات.
`content`	object	كائن محتوى البريد الإلكتروني. يتم تعبئته فقط بواسطة `Get`؛ `null` في استجابات `Create` و `List` و `Update`.
`preview_settings`	object	إعدادات معاينة المحرر العشوائية.
`created`	string (RFC 3339)	الطابع الزمني للإنشاء.
`updated`	string (RFC 3339)	الطابع الزمني لآخر تحديث.

كائن محتوى البريد الإلكتروني

الحقل	النوع	الوصف
`sender_info`	object	كائن معلومات المرسل — عناوين `from` و `reply_to`.
`subject`	object (map)	موضوع لكل لغة، على سبيل المثال `{ "en": "Subject", "default": "Subject" }`.
`unlayer` / `pushwoosh` / `smartcards`	object	محتوى المحرر. يجب تعيين واحد بالضبط من هذه — يحدد أي محرر أنتج (وسيعرض) القالب. انظر أنواع المحرر أدناه.

أنواع المحرر

النوع	الحقل	الحقول الفرعية المطلوبة	الوصف
`unlayer`	`html`, `localization_data`, `editor_config`	`editor_config`, `localization_data`	محرر كتل السحب والإفلات (Unlayer). `editor_config` هو JSON تصميم Unlayer.
`pushwoosh`	`html`, `localization_data`	`localization_data`	محرر Pushwoosh الخاص القائم على HTML. يوصى به للقوالب التي يتم إنشاؤها برمجيًا/عبر واجهة برمجة التطبيقات.
`smartcards`	`html`, `localization_data`, `content`	`content`, `localization_data`	محرر كتل Smart Cards؛ `content` هو JSON الخاص بالمحرر.

في كل نوع، html هو الإخراج المعروض. localization_data هو محتوى المحرر الخاص بكل لغة: كائن مفتاحه هو رمز اللغة (en، es، default، …)، حيث تكون كل قيمة هي نسخة تلك اللغة من حقول المحرر. شكله الداخلي خاص بالمحرر وغير شفاف لهذه الواجهة البرمجية — تقوم الواجهة بتخزينه وإعادته كما هو. وهو مطلوب عند Create/Update لكل نوع (أرسل {} إذا لم يكن هناك شيء للترجمة).

عندما تعيد واجهة برمجة التطبيقات content (حاليًا فقط Get، نظرًا لأن Create و Update لا تعيدانه)، فإنها تضمن عرض لغة واحدة كـ default: إذا لم ترسل مفتاح default بنفسك، فإنها ترفع en (أو، في حالة فشل ذلك، أي مفتاح لغة يأتي أولاً) إلى default، مع إعادة تسميته — يتم الاحتفاظ بكل لغة أخرى أرسلتها كما هي. يحصل subject على نفس المعاملة. هذا يختلف عن Clone، الذي يحتفظ فقط بقيمة اللغة الافتراضية هذه ويسقط الباقي.

يتم تطبيق إعادة التسمية هذه فقط عند بناء الاستجابة — ولكن لا يتم التراجع عنها عند الكتابة. إذا أخذت استجابة Get كما هي وأرسلتها مباشرة إلى Update، فإن المفتاح المروج (على سبيل المثال en) هو الآن حرفيًا default، ويقوم Update بتخزين ما ترسله بالضبط: يختفي مفتاح en الأصلي من ذلك الحين فصاعدًا، بشكل دائم. إذا كنت بحاجة إلى الاحتفاظ بمفتاح اللغة الأصلي، أعد تسمية default مرة أخرى إليه بنفسك قبل استدعاء Update.

يمكن أن يتضمن النص داخل html أو قيمة localization_data علامات المحتوى الديناميكي، على سبيل المثال {name|string|there} — يتم حل هذه العلامات مقابل علامات جهاز المستلم عند إرسال البريد الإلكتروني بالفعل. لا تقوم واجهة برمجة التطبيقات هذه بحلها؛ إنها تخزن وتعيد أي نص تضعه هناك.

كائن معلومات المرسل

الحقل	النوع	الوصف
`from`	object	`{ "email": string, "name": string }` — عنوان المرسل.
`reply_to`	object	`{ "email": string, "name": string }` — عنوان الرد.

يجب أن يكون كلا الحقلين الفرعيين email، عندما لا يكونان فارغين، عنواني بريد إلكتروني صالحين.

مواضيع ذات صلة

إعلام

مرجع حمولة البريد الإلكتروني

مرجع نقطة Customer Journey