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

createEmailMessage مهمل

ينشئ رسالة بريد إلكتروني.

POST https://api.pushwoosh.com/json/1.3/createEmailMessage

معلمات نص الطلب

الاسم	النوع	مطلوب	الوصف
auth	`string`	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
application	`string`	نعم	رمز تطبيق Pushwoosh
notifications	`array`	نعم	مصفوفة JSON تحتوي على تفاصيل رسالة البريد الإلكتروني. انظر جدول معلمات الإشعارات أدناه.

معلمات الإشعارات

الاسم	النوع	مطلوب	الوصف
send_date	`string`	نعم	يحدد متى يتم إرسال البريد الإلكتروني. التنسيق: `YYYY-MM-DD HH:mm` أو `"now"`.
preset	`string`	نعم	رمز البريد الإلكتروني المُعد مسبقًا. انسخه من شريط عنوان URL في محرر محتوى البريد الإلكتروني في لوحة تحكم Pushwoosh.
subject	`string` أو `object`	لا	سطر موضوع البريد الإلكتروني. سيكون البريد الإلكتروني دائمًا بلغة المحتوى. إذا لم يحتوي `subject` على لغة مطابقة لـ `content`، فسيكون الموضوع فارغًا.
content	`string` أو `object`	لا	محتوى نص البريد الإلكتروني. يمكن أن يكون سلسلة نصية لمحتوى HTML عادي أو كائنًا للإصدارات المترجمة.
attachments	`array`	لا	مرفقات البريد الإلكتروني. يتوفر مرفقان فقط. يجب ألا يتجاوز كل مرفق 1 ميغابايت (بترميز base64).
list_unsubscribe	`string`	لا	يسمح بتعيين عنوان URL مخصص لرأس “Link-Unsubscribe”.
campaign	`string`	لا	رمز الحملة لربط البريد الإلكتروني بحملة معينة.
ignore_user_timezone	`boolean`	لا	إذا كانت القيمة `true`، يتم إرسال البريد الإلكتروني فورًا، مع تجاهل المناطق الزمنية للمستخدم.
timezone	`string`	لا	يرسل البريد الإلكتروني وفقًا للمنطقة الزمنية للمستخدم. مثال: `"America/New_York"`.
filter	`string`	لا	يرسل البريد الإلكتروني للمستخدمين الذين يطابقون شرط تصفية محدد.
devices	`array`	لا	قائمة بعناوين البريد الإلكتروني (بحد أقصى 1000) لإرسال رسائل بريد إلكتروني مستهدفة. إذا تم استخدامها، يتم إرسال الرسالة فقط إلى هذه العناوين. يتم تجاهلها إذا تم استخدام مجموعة التطبيقات.
use_auto_registration	`boolean`	لا	إذا كانت القيمة `true`، يتم تسجيل رسائل البريد الإلكتروني من معلمة `devices` تلقائيًا.
users	`array`	لا	إذا تم تعيينها، سيتم تسليم رسالة البريد الإلكتروني فقط إلى معرفات المستخدم (User ID) المحددة (المسجلة عبر استدعاء /registerEmail). لا يزيد عن 1000 معرف مستخدم في المصفوفة. إذا تم تحديد معلمة “devices”، فسيتم تجاهل معلمة “users”.
dynamic_content_placeholders	`object`	لا	عناصر نائبة للمحتوى الديناميكي بدلاً من قيم علامات الجهاز.
conditions	`array`	لا	شروط التجزئة باستخدام العلامات. مثال: `[["Country", "EQ", "BR"]]`.
from	`object`	لا	تحديد اسم مرسل وبريد إلكتروني مخصص، متجاوزًا الإعداد الافتراضي في خصائص التطبيق.
reply-to	`object`	لا	تحديد بريد إلكتروني مخصص للرد، متجاوزًا الإعداد الافتراضي في خصائص التطبيق.
bcc	`array`	لا	BCC (نسخة كربونية عمياء): مصفوفة من عناوين البريد الإلكتروني التي تتلقى نسخة من البريد الإلكتروني دون أن يراها المستلمون الآخرون.
email_type	`string`	لا	تحديد نوع البريد الإلكتروني: `"marketing"` أو `"transactional"`. إذا تم حذفه، فلن يتلقى المستخدمون الذين لديهم `PW_ControlGroup: true` الرسالة.
email_category	`string`	مطلوب عندما يكون `email_type` هو `"marketing"`.	تحديد أحد أسماء الفئات التي تم تكوينها في مركز تفضيلات الاشتراك (مثل النشرة الإخبارية، العروض الترويجية، تحديثات المنتج).
transactionId	`string`	لا	معرف رسالة فريد لمنع إعادة الإرسال في حالة وجود مشاكل في الشبكة. يتم تخزينه على جانب Pushwoosh لمدة 5 دقائق.
capping_days	`integer`	لا	عدد الأيام (بحد أقصى 30) لتطبيق تحديد التكرار لكل جهاز. ملاحظة: تأكد من تكوين تحديد التكرار العالمي في لوحة التحكم.
capping_count	`integer`	لا	الحد الأقصى لعدد رسائل البريد الإلكتروني التي يمكن إرسالها من تطبيق معين إلى جهاز معين خلال فترة `capping_days`. في حالة تجاوز الرسالة التي تم إنشاؤها حد `capping_count` لجهاز ما، فلن يتم إرسالها إلى ذلك الجهاز.
capping_exclude	`boolean`	لا	إذا تم التعيين على `true`، فلن يتم احتساب هذا البريد الإلكتروني ضمن تحديد التكرار للرسائل المستقبلية.
capping_avoid	`boolean`	لا	إذا تم التعيين على `true`، فلن يتم تطبيق تحديد التكرار على هذا البريد الإلكتروني المحدد.
send_rate	`integer`	لا	تحديد عدد الرسائل التي يمكن إرسالها في الثانية عبر جميع المستخدمين. يساعد على منع الحمل الزائد على الواجهة الخلفية أثناء عمليات الإرسال الكبيرة.
send_rate_avoid	`boolean`	لا	إذا تم التعيين على `true`، فلن يتم تطبيق حد التقييد على هذا البريد الإلكتروني المحدد.

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

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // مطلوب. رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "application": "APPLICATION_CODE",  // مطلوب. رمز تطبيق Pushwoosh.
    "notifications": [{
      "send_date": "now",               // مطلوب. YYYY-MM-DD HH:mm أو 'now'
      "preset": "ERXXX-32XXX",          // مطلوب. انسخ رمز البريد الإلكتروني المُعد مسبقًا من شريط عنوان URL
                                        //           لصفحة محرر محتوى البريد الإلكتروني في لوحة تحكم Pushwoosh.
      "subject": {                      // اختياري. سطر موضوع رسالة البريد الإلكتروني.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // اختياري. محتوى نص البريد الإلكتروني.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // اختياري. مرفقات البريد الإلكتروني
        "name": "image.png",            //           "name" - اسم الملف
        "content": "iVBANA...AFTkuQmwC" //           "content" - محتوى الملف بترميز base64
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // اختياري. يسمح بتعيين عنوان URL مخصص لرأس "Link-Unsubscribe"
      "campaign": "CAMPAIGN_CODE",      // اختياري. لتعيين رسالة البريد الإلكتروني هذه لحملة معينة،
                                        //           أضف رمز الحملة هنا.
      "ignore_user_timezone": true,     // اختياري.
      "timezone": "America/New_York",   // اختياري. حدد لإرسال الرسالة وفقًا
                                        //           للمنطقة الزمنية المحددة على جهاز المستخدم.
      "filter": "FILTER_NAME",          // اختياري. أرسل الرسالة إلى مستخدمين محددين يستوفون شروط التصفية.
      "devices": [                      // اختياري. حدد عناوين البريد الإلكتروني لإرسال رسائل بريد إلكتروني مستهدفة.
        "email_address1",               //           لا يزيد عن 1000 عنوان في المصفوفة.
        "email_address2"                //           إذا تم التعيين، سيتم إرسال الرسالة فقط إلى العناوين الموجودة
      ],                                //           في القائمة. يتم تجاهله إذا تم استخدام مجموعة التطبيقات.
      "use_auto_registration": true,    // اختياري. تسجيل رسائل البريد الإلكتروني المحددة في معلمة "devices" تلقائيًا
      "users": [                        // اختياري. إذا تم التعيين، سيتم تسليم رسالة البريد الإلكتروني فقط إلى
        "userId1",                      //           معرفات المستخدم المحددة (المسجلة عبر استدعاء /registerEmail).
        "userId2"                       //           لا يزيد عن 1000 معرف مستخدم في المصفوفة.
      ],                                //           إذا تم تحديد معلمة "devices"،
                                        //           فسيتم تجاهل معلمة "users".
      "dynamic_content_placeholders": { // اختياري. عناصر نائبة للمحتوى الديناميكي بدلاً من قيم علامات الجهاز.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // اختياري. شروط التجزئة، انظر الملاحظة أدناه.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // اختياري. تحديد اسم مرسل وعنوان بريد إلكتروني للمرسل
        "name": "alias from",           //           لاستبدال "اسم المرسل" و "بريد المرسل" الافتراضي
        "email": "from-email@email.com" //           المعين في خصائص التطبيق.
      },
      "reply-to": {                     // اختياري. تحديد عنوان بريد إلكتروني لاستبدال
        "name": "alias reply to ",      //           "الرد على" الافتراضي المعين في خصائص التطبيق.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // اختياري. BCC: مصفوفة من عناوين البريد الإلكتروني التي تتلقى نسخة دون أن يراها المستلمون الآخرون.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // اختياري. "marketing" أو "transactional".
                                        // إذا تم حذفه، فلن يتلقى المستخدمون الذين لديهم PW_ControlGroup: true الرسالة.
      "email_category": "category name",// مطلوب عندما يكون email_type هو "marketing". اسم الفئة.
      "transactionId": "unique UUID",   // اختياري. معرف رسالة فريد لمنع إعادة الإرسال
                                        //           في حالة وجود مشاكل في الشبكة. يتم تخزينه على جانب
                                        //           Pushwoosh لمدة 5 دقائق.
      // معلمات تحديد التكرار. تأكد من تكوين تحديد التكرار العالمي في لوحة التحكم.
      // لا ينطبق تحديد التكرار على الرسائل المتعلقة بالمعاملات.
      // في جميع الحالات الأخرى، بما في ذلك "email_type" المحذوف، يتم تطبيق تحديد التكرار.
      "capping_days": 30,               // اختياري. عدد الأيام لتحديد التكرار (بحد أقصى 30 يومًا)
      "capping_count": 10,              // اختياري. الحد الأقصى لعدد رسائل البريد الإلكتروني التي يمكن إرسالها من
                                        //           تطبيق معين إلى جهاز معين خلال فترة 'capping_days'
                                        //           . في حالة تجاوز الرسالة التي تم إنشاؤها
                                        //           حد 'capping_count' لجهاز ما، فلن
                                        //           يتم إرسالها إلى ذلك الجهاز.
      "capping_exclude": true,          // اختياري. إذا تم التعيين على true، فلن يتم
                                        //           احتساب هذا البريد الإلكتروني ضمن تحديد التكرار للرسائل المستقبلية.
      "capping_avoid": true,            // اختياري. إذا تم التعيين على true، فلن يتم تطبيق تحديد التكرار على
                                        //           هذا البريد الإلكتروني المحدد.
      "send_rate": 100,                 // اختياري. حد التقييد.
                                        //           تحديد عدد الرسائل التي يمكن إرسالها في الثانية عبر جميع المستخدمين.
                                        //           يساعد على منع الحمل الزائد على الواجهة الخلفية أثناء عمليات الإرسال الكبيرة.
      "send_rate_avoid": true,          // اختياري. إذا تم التعيين على true، فلن يتم تطبيق حد التقييد على
                                        //           هذا البريد الإلكتروني المحدد.
    }]
  }
}

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

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}

شروط العلامة

كل شرط علامة هو مصفوفة مثل [tagName, operator, operand] حيث

tagName: اسم العلامة
operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
operand: سلسلة نصية | عدد صحيح | مصفوفة | تاريخ

وصف المعامل

EQ: قيمة العلامة تساوي المعامل؛
IN: قيمة العلامة تتقاطع مع المعامل (يجب أن يكون المعامل دائمًا مصفوفة)؛
NOTEQ: قيمة العلامة لا تساوي المعامل؛
NOTIN: قيمة العلامة لا تتقاطع مع المعامل (يجب أن يكون المعامل دائمًا مصفوفة)؛
GTE: قيمة العلامة أكبر من أو تساوي المعامل؛
LTE: قيمة العلامة أصغر من أو تساوي المعامل؛
BETWEEN: قيمة العلامة أكبر من أو تساوي قيمة المعامل الدنيا ولكنها أصغر من أو تساوي قيمة المعامل القصوى (يجب أن يكون المعامل دائمًا مصفوفة).

علامات السلسلة النصية

العوامل الصالحة: EQ, IN, NOTEQ, NOTIN
المعاملات الصالحة:

EQ, NOTEQ: يجب أن يكون المعامل سلسلة نصية؛
IN, NOTIN: يجب أن يكون المعامل مصفوفة من السلاسل النصية مثل ["value 1", "value 2", "value N"]؛

علامات الأعداد الصحيحة

العوامل الصالحة: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
المعاملات الصالحة:

EQ, NOTEQ, GTE, LTE: يجب أن يكون المعامل عددًا صحيحًا؛
IN, NOTIN: يجب أن يكون المعامل مصفوفة من الأعداد الصحيحة مثل [value 1, value 2, value N]؛
BETWEEN: يجب أن يكون المعامل مصفوفة من الأعداد الصحيحة مثل [min_value, max_value].

علامات التاريخ

العوامل الصالحة: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
المعاملات الصالحة:

"YYYY-MM-DD 00:00" (سلسلة نصية)
طابع زمني يونكس 1234567890 (عدد صحيح)
"N days ago" (سلسلة نصية) للعوامل EQ, BETWEEN, GTE, LTE

علامات القيم المنطقية

العوامل الصالحة: EQ
المعاملات الصالحة: 0, 1, true, false

علامات القائمة

العوامل الصالحة: IN
المعاملات الصالحة: يجب أن يكون المعامل مصفوفة من السلاسل النصية مثل ["value 1", "value 2", "value N"].

registerEmail

يسجل عنوان البريد الإلكتروني للتطبيق.

POST https://api.pushwoosh.com/json/1.3/registerEmail

رؤوس الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز جهاز API للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك.

نص الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
email*	string	عنوان البريد الإلكتروني.
language	string	لغة الجهاز. يجب أن يكون رمزًا من حرفين صغيرين وفقًا لمعيار ISO-639-1.
userId	string	معرف المستخدم (User ID) لربطه بعنوان البريد الإلكتروني.
tz_offset	integer	إزاحة المنطقة الزمنية بالثواني.
tags	object	قيم العلامات لتعيينها للجهاز المسجل.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 210,
  "status_message": "this hwid (email) is blacklisted",
  "response": null
}

{
  "status_code": 400,
  "status_message": "Missing required argument: email",
  "response": null
}

{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}

{
  "status_code": 500,
  "status_message": "Internal server error",
  "response": null
}

{
  "request": {
    "application": "APPLICATION_CODE",   // مطلوب. رمز تطبيق Pushwoosh.
    "email":"email@domain.com",          // مطلوب. عنوان البريد الإلكتروني المراد تسجيله.
    "language": "en",                    // اختياري. لغة الجهاز.
    "userId": "userId",                  // اختياري. معرف المستخدم لربطه بعنوان البريد الإلكتروني.
    "tz_offset": 3600,                   // اختياري. إزاحة المنطقة الزمنية بالثواني.
    "tags": {                            // اختياري. قيم العلامات لتعيينها للجهاز المسجل.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // يحدد قائمة القيم للعلامات من نوع القائمة
       "DateTag": "2024-10-02 22:11",    // لاحظ أن الوقت يجب أن يكون بتوقيت UTC
       "BooleanTag": true                // القيم الصالحة هي: true, false
    }
  }
}

رموز الاستجابة

تعيد واجهة برمجة التطبيقات العامة النتيجة في status_code. استخدم الجدول أدناه لتحديد ما إذا كان يجب إعادة محاولة استدعاء فاشل.

`status_code`	المعنى	إعادة المحاولة؟
`200`	نجاح — تم تسجيل عنوان البريد الإلكتروني.	لا — تم.
`210`	خطأ في الوسيطة/التحقق — تم فهم الطلب ولكن تم رفضه (عنوان في القائمة السوداء، بريد إلكتروني غير صالح أو مؤقت، منصة خاطئة لخطة الحساب). انظر رسائل الخطأ 210 أدناه.	لا — نفس الطلب يعيد نفس `210`. سجل العنوان وتجاوزه.
`400`	طلب غير صحيح — JSON غير صالح أو حقل مطلوب مفقود.	لا — أصلح الطلب، لا تكرره.
`403`	محظور — رمز جهاز API غير صالح أو مقيد.	لا — أصلح التفويض.
`500`	خطأ داخلي في الخادم — مشكلة مؤقتة في البنية التحتية أو انتهاء المهلة.	نعم، مع تراجع أسي — الحالة العابرة الوحيدة.

رسائل الخطأ 210

تحمل الاستجابة 210 السبب المحدد في status_message.

`status_message`	المعنى
`this hwid (email) is blacklisted`	العنوان موجود في قائمة الحظر بعد ارتداد دائم (صلب) ولن يتم إعادة تسجيله.
`hwid (email) is invalid` / `has invalid semantic`	فشل التحقق من صحة العنوان.
`hwid (email) is empty`	لم يتم تقديم أي عنوان.
`hwid (email) has invalid count of parts`	`@` مفقود أو إضافي.
`hwid (email) has invalid local part`	الجزء قبل `@` غير صالح.
`hwid (email) has invalid domain part`	جزء النطاق غير صالح.
`hwid (email) has disposable domain`	يستخدم العنوان نطاق بريد إلكتروني مؤقت/للاستخدام مرة واحدة (مثل 10minutemail).
`hwid is not valid`	`hwid` نفسه غير صحيح.
`only email platform allowed for Email Only subscription`	الحساب على خطة بريد إلكتروني فقط ولا يمكنه تسجيل أجهزة غير بريد إلكتروني.

deleteEmail

يزيل عنوان البريد الإلكتروني من قاعدة المستخدمين الخاصة بك.

POST https://api.pushwoosh.com/json/1.3/deleteEmail

رؤوس الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز جهاز API للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك.

نص الطلب

الاسم	النوع	الوصف
application	string	رمز تطبيق Pushwoosh
email	string	عنوان البريد الإلكتروني المستخدم في طلب `/registerEmail`.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "request": {
    "application": "APPLICATION_CODE",  // مطلوب. رمز تطبيق Pushwoosh
    "email": "email@domain.com"         // مطلوب. البريد الإلكتروني المراد حذفه من مشتركي التطبيق.
  }
}

setEmailTags

يضبط قيم العلامات لعنوان البريد الإلكتروني.

POST https://api.pushwoosh.com/json/1.3/setEmailTags

رؤوس الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز جهاز API للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك.

نص الطلب

الاسم	النوع	الوصف
application	string	رمز تطبيق Pushwoosh
email	string	عنوان البريد الإلكتروني.
tags	object	كائن JSON للعلامات المراد تعيينها، أرسل ‘null’ لإزالة القيمة.
userId	string	معرف المستخدم (User ID) المرتبط بعنوان البريد الإلكتروني.

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}

{
  "request": {
    "email": "email@domain.com",                  // مطلوب. عنوان البريد الإلكتروني لتعيين العلامات له.
    "application": "APPLICATION_CODE",            // مطلوب. رمز تطبيق Pushwoosh.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // الوقت بتوقيت UTC
      "BooleanTag": true                          // القيم الصالحة هي: true, false
    },
    "userId": "userId"                            // اختياري. معرف المستخدم المرتبط بعنوان البريد الإلكتروني.
  }
}

registerEmailUser

يربط معرف مستخدم (User ID) خارجي بعنوان بريد إلكتروني محدد.

POST https://api.pushwoosh.com/json/1.3/registerEmailUser

يمكن استخدامه في استدعاء واجهة برمجة التطبيقات /createEmailMessage (معلمة ‘users’).

رؤوس الطلب

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	رمز جهاز API للوصول إلى واجهة برمجة تطبيقات الجهاز. استبدل `XXXX` برمز جهاز API الفعلي الخاص بك.

نص الطلب

الاسم	النوع	الوصف
application*	string	رمز تطبيق Pushwoosh
email*	string	عنوان البريد الإلكتروني.
userId*	string	معرف المستخدم (User ID) لربطه بعنوان البريد الإلكتروني.
tz_offset	integer	إزاحة المنطقة الزمنية بالثواني.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "status_code": 400,
  "status_message": "Request format is not valid."
}

{
  "status_code": 403,
  "status_message": "Forbidden."
}

{
  "request": {
    "application": "APPLICATION_CODE", // مطلوب. رمز تطبيق Pushwoosh.
    "email": "email@domain.com",       // مطلوب. عنوان البريد الإلكتروني للمستخدم.
    "userId": "userId",                // مطلوب. معرف المستخدم لربطه بعنوان البريد الإلكتروني.
    "tz_offset": 3600                  // اختياري. إزاحة المنطقة الزمنية بالثواني.
  }
}