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

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	لا	إذا تم تعيينها، سيتم تسليم رسالة البريد الإلكتروني فقط إلى معرفات المستخدم المحددة (المسجلة عبر استدعاء /registerEmail). لا يزيد عن 1000 معرف مستخدم في مصفوفة. إذا تم تحديد معلمة “devices”، فسيتم تجاهل معلمة “users”.
dynamic_content_placeholders	object	لا	عناصر نائبة للمحتوى الديناميكي بدلاً من قيم علامات الجهاز.
conditions	array	لا	شروط التجزئة باستخدام العلامات. مثال: [["Country", "EQ", "BR"]].
from	object	لا	حدد اسم مرسل وبريد إلكتروني مخصصين، متجاوزًا الإعداد الافتراضي في خصائص التطبيق.
reply-to	object	لا	حدد بريدًا إلكترونيًا مخصصًا للرد، متجاوزًا الإعداد الافتراضي في خصائص التطبيق.
email_type	string	لا	حدد نوع البريد الإلكتروني: "marketing" أو "transactional".
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"
      },
      "email_type": "marketing",        // اختياري. "marketing" أو "transactional".
      "email_category": "category name",// مطلوب عندما يكون email_type هو "marketing". اسم الفئة.
      "transactionId": "unique UUID",   // اختياري. معرف رسالة فريد لمنع إعادة الإرسال
                                        //           في حالة مشاكل الشبكة. يتم تخزينه على جانب
                                        //           Pushwoosh لمدة 5 دقائق.
      // معلمات تحديد التكرار. تأكد من تكوين تحديد التكرار العالمي في لوحة التحكم.
      "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، فلن يتم تطبيق حد التقييد على
                                        //           هذا البريد الإلكتروني المحدد.
    }]
  }
}

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

200

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

403

{
  "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: string | integer | array | date

وصف المعامل

• 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"].

خطر

تذكر أنه لا ينبغي استخدام معلمات “filter” و “conditions” معًا.
أيضًا، سيتم تجاهلهما كليهما، إذا تم استخدام معلمة “devices” في نفس الطلب.

ملاحظة

علامات البلد واللغة

قيمة علامة اللغة هي رمز من حرفين صغيرين وفقًا لـ ISO-639-1
قيمة علامة البلد هي رمز من حرفين كبيرين وفقًا لـ ISO_3166-2
على سبيل المثال، لإرسال إشعار فوري للمشتركين الناطقين بالبرتغالية في البرازيل، ستحتاج إلى تحديد الشرط التالي: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

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	معرف المستخدم لربطه بعنوان البريد الإلكتروني.
tz_offset	integer	إزاحة المنطقة الزمنية بالثواني.
tags	object	قيم العلامات لتعيينها للجهاز المسجل.

200

{
  "status_code": 200,
  "status_message": "OK",
  "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
    }
  }
}

deleteEmail

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

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

ترويسات الطلب

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

نص الطلب

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

200

{
  "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	معرف المستخدم المرتبط بعنوان البريد الإلكتروني.

200

{
  "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"                            // اختياري. معرف المستخدم المرتبط بعنوان البريد الإلكتروني.
  }
}

ملاحظة

بالنسبة لأنواع الأجهزة الأخرى، سيتم إرجاع 200 OK، على الرغم من عدم حفظ العلامات.

تنبيه

يرجى تجنب تعيين أكثر من 50 قيمة علامة في طلب /setEmailTags واحد.

registerEmailUser

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

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

ملاحظة

يرجى ملاحظة أن هذه الطريقة لا تسجل عنوان بريد إلكتروني في قاعدة المستخدمين الخاصة بك؛ يجب استخدامها فقط لتعيين معرفات المستخدمين لعناوين البريد الإلكتروني التي تم تسجيلها بالفعل بواسطة طلب /registerEmail.

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

ترويسات الطلب

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

نص الطلب

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

200

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

400

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

403

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

مثال

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

ملاحظة

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