Email API

createEmailMessage

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

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

Request body parameters

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

Notifications parameters

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

Request example

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // مطلوب. API access token من لوحة تحكم Pushwoosh
    "application": "APPLICATION_CODE",  // مطلوب. Pushwoosh application code.
    "notifications": [{
      "send_date": "now",               // مطلوب. YYYY-MM-DD HH:mm أو 'now'
      "preset": "ERXXX-32XXX",          // مطلوب. انسخ Email preset code من شريط 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"                //           إذا تم تعيينه، سيتم إرسال الرسالة فقط إلى العناوين الموجودة في
      ],                                //           القائمة. يتم تجاهله إذا تم استخدام Application Group.
      "use_auto_registration": true,    // اختياري. تسجيل رسائل البريد الإلكتروني المحددة في معلمة "devices" تلقائيًا
      "users": [                        // اختياري. إذا تم تعيينه، سيتم تسليم رسالة البريد الإلكتروني فقط إلى
        "userId1",                      //           User IDs المحددة (المسجلة عبر استدعاء /registerEmail).
        "userId2"                       //           لا يزيد عن 1000 معرف مستخدم في المصفوفة.
      ],                                //           إذا تم تحديد المعلمة "devices"،
                                        //           سيتم تجاهل المعلمة "users".
      "dynamic_content_placeholders": { // اختياري. عناصر نائبة للمحتوى الديناميكي بدلاً من قيم علامات الجهاز.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // اختياري. شروط التقسيم، انظر الملاحظة أدناه.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // اختياري. تحديد اسم المرسل وعنوان البريد الإلكتروني للمرسل
        "name": "alias from",           //           لاستبدال "From name" و "From email" الافتراضيين
        "email": "from-email@email.com" //           التي تم إعدادها في خصائص التطبيق.
      },
      "reply-to": {                     // اختياري. تحديد عنوان بريد إلكتروني لاستبدال
        "name": "alias reply to ",      //           "Reply to" الافتراضي الذي تم إعداده في خصائص التطبيق.
        "email": "reply-to@email.com"
      },
      "transactionId": "unique UUID",   // اختياري. معرف رسالة فريد لمنع إعادة الإرسال
                                        //           في حالة مشاكل الشبكة. يتم تخزينه على جانب
                                        //           Pushwoosh لمدة 5 دقائق.
      // معلمات تحديد التكرار (Frequency capping). تأكد من تكوين Global frequency capping في لوحة التحكم.
      "capping_days": 30,               // اختياري. عدد الأيام لتحديد التكرار (بحد أقصى 30 يومًا)
      "capping_count": 10,              // اختياري. الحد الأقصى لعدد رسائل البريد الإلكتروني التي يمكن إرسالها من
                                        //           تطبيق معين إلى جهاز معين خلال فترة 'capping_days'.
                                        //           في حالة تجاوز الرسالة التي تم إنشاؤها حد
                                        //           'capping_count' لجهاز ما، فلن
                                        //           يتم إرسالها إلى ذلك الجهاز.
      "capping_exclude": true,          // اختياري. إذا تم تعيينه على true، فلن يتم
                                        //           احتساب هذا البريد الإلكتروني ضمن الحد الأقصى لرسائل البريد الإلكتروني المستقبلية.
      "capping_avoid": true,            // اختياري. إذا تم تعيينه على true، فلن يتم تطبيق الحد الأقصى على
                                        //           هذا البريد الإلكتروني المحدد.
      "send_rate": 100,                 // اختياري. حد الاختناق (Throttling limit).
                                        //           الحد من عدد الرسائل التي يمكن إرسالها في الثانية عبر جميع المستخدمين.
                                        //           يساعد في منع التحميل الزائد على الواجهة الخلفية أثناء عمليات الإرسال كبيرة الحجم.
      "send_rate_avoid": true,          // اختياري. إذا تم تعيينه على true، فلن يتم تطبيق حد الاختناق على
                                        //           هذا البريد الإلكتروني المحدد.
    }]
  }
}

Response examples

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

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

Tag conditions

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

tagName: اسم العلامة (tag)
operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
operand: string | integer | array | date

Operand description

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

String tags

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

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

Integer tags

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

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

Date tags

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

"YYYY-MM-DD 00:00" (string)
unix timestamp 1234567890 (integer)
"N days ago" (string) للمشغلات EQ, BETWEEN, GTE, LTE

Boolean tags

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

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

registerEmail

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

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

Request headers

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	API Device Token للوصول إلى Device API. استبدل `XXXX` بـ Device API token الفعلي الخاص بك.

Request body

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

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

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

deleteEmail

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

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

Request headers

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	API Device Token للوصول إلى Device API. استبدل `XXXX` بـ Device API token الفعلي الخاص بك.

Request body

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

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

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

setEmailTags

يعين قيم العلامات (tag values) لعنوان البريد الإلكتروني.

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

Request headers

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	API Device Token للوصول إلى Device API. استبدل `XXXX` بـ Device API token الفعلي الخاص بك.

Request body

الاسم	النوع	الوصف
application	string	Pushwoosh application code
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 application code.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // الوقت بتوقيت UTC
      "BooleanTag": true                          // القيم الصالحة هي: true, false
    },
    "userId": "userId"                            // اختياري. User ID المرتبط بعنوان البريد الإلكتروني.
  }
}

registerEmailUser

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

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

يمكن استخدامه في استدعاء API /createEmailMessage (المعلمة ‘users’).

Request headers

الاسم	مطلوب	القيمة	الوصف
Authorization	نعم	Token `XXXX`	API Device Token للوصول إلى Device API. استبدل `XXXX` بـ Device API token الفعلي الخاص بك.

Request body

الاسم	النوع	الوصف
application*	string	Pushwoosh application code
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 application code.
    "email": "email@domain.com",       // مطلوب. عنوان البريد الإلكتروني للمستخدم.
    "userId": "userId",                // مطلوب. User ID لربطه بعنوان البريد الإلكتروني.
    "tz_offset": 3600                  // اختياري. إزاحة المنطقة الزمنية بالثواني.
  }
}

Email API

createEmailMessage

Request body parameters

Notifications parameters

Request example

Response examples

Tag conditions

Operand description

String tags

Integer tags

Date tags

Boolean tags

List tags

registerEmail

Request headers

Request body

deleteEmail

Request headers

Request body

setEmailTags

Request headers

Request body

registerEmailUser

Request headers

Request body