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

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

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

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

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

المصادقة

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

Authorization: Api YOUR_API_TOKEN

الاصطلاحات

تسمية الحقول: تقبل أجسام الطلبات ومعلمات الاستعلام/المسار lowerCamelCase (على سبيل المثال، previewSettings، searchByLabel، includeHtml) — يقوم الخادم بفك ترميز أي من الحالتين. يتم دائمًا ترميز الاستجابات باستخدام أسماء حقول البروتو، في 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 بالفعل — أسماء حقول البروتو 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` هو تصميم Unlayer JSON.
`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، عندما لا يكونان فارغين، عنواني بريد إلكتروني صالحين.

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

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

المصادقة

الاصطلاحات

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

نقاط النهاية

إنشاء

جسم الطلب

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

الاستجابة

قائمة

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

الاستجابة

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

الحصول على

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

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

الاستجابة

تحديث

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

جسم الطلب

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

الاستجابة

حذف

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

الاستجابة

استنساخ

جسم الطلب

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

الاستجابة

مرجع الكائن

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

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

أنواع المحرر

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

ذات صلة