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

تم إهمال /createEmailMessage

يجب أن تستخدم عمليات التكامل الجديدة واجهة برمجة تطبيقات المراسلة v2 — مرر platforms: ["EMAIL"] وكتلة email_payload إلى Notify. انظر دليل الترحيل.

createEmailMessage مهمل

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

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

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

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

نصيحة

مرر رأس X-Request-ID لربط الرسالة المنشأة بطلبك للتتبع من طرف إلى طرف — انظر معرف الطلب.

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

الاسم	النوع	مطلوب	الوصف
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". إذا تم حذفه، تُعامل الرسالة على أنها 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",         // required. API access token from Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code.
    "notifications": [{
      "send_date": "now",               // required. YYYY-MM-DD HH:mm  OR 'now'
      "preset": "ERXXX-32XXX",          // required. Copy Email preset code from the URL bar of
                                        //           the Email Content editor page in Pushwoosh Control Panel.
      "subject": {                      // optional. Email message subject line.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // optional. Email body content.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // optional. Email attachments
        "name": "image.png",            //           "name" - file name
        "content": "iVBANA...AFTkuQmwC" //           "content" - base64 encoded content of the file
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // optional. Allow to set custom URL for "Link-Unsubscribe" header
      "campaign": "CAMPAIGN_CODE",      // optional. To assign this email message to a particular campaign,
                                        //           add a campaign code here.
      "ignore_user_timezone": true,     // optional.
      "timezone": "America/New_York",   // optional. Specify to send the message according to
                                        //           timezone set on user's device.
      "filter": "FILTER_NAME",          // optional. Send the message to specific users meeting filter conditions.
      "devices": [                      // optional. Specify email addresses to send targeted email messages.
        "email_address1",               //           Not more than 1000 addresses in an array.
        "email_address2"                //           If set, the message will only be sent to the addresses on
      ],                                //           the list. Ignored if the Application Group is used.
      "use_auto_registration": true,    // optional. Automatically register emails specified in "devices" parameter
      "users": [                        // optional. If set, the email message will only be delivered to the
        "userId1",                      //           specified user IDs (registered via /registerEmail call).
        "userId2"                       //           Not more than 1000 user IDs in an array.
      ],                                //           If the "devices" parameter is specified,
                                        //           the "users" parameter will be ignored.
      "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tag values.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // optional. Segmentation conditions, see remark below.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // optional. Specify a sender name and sender email address
        "name": "alias from",           //           to replace the default "From name" and "From email"
        "email": "from-email@email.com" //           set up in application properties.
      },
      "reply-to": {                     // optional. Specify an email address to replace the
        "name": "alias reply to ",      //           default "Reply to" set up in application properties.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // optional. BCC: array of email addresses that receive a copy without other recipients seeing them.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // optional. "marketing" or "transactional".
                                        // If omitted, treated as transactional: delivered to everyone.
                                        // Marketing messages are not delivered to control group members.
      "email_category": "category name",// required when email_type is "marketing". Category name.
      "transactionId": "unique UUID",   // optional. Unique message identifier to prevent re-sending
                                        //           in case of network problems. Stored on the side
                                        //           of Pushwoosh for 5 minutes.
      // Frequency capping params. Ensure that Global frequency capping is configured in the Control Panel.
      // Frequency capping does not apply to transactional messages.
      // In all other cases, including omitted "email_type", frequency capping applies.
      "capping_days": 30,               // optional. Amount of days for frequency capping (max 30 days)
      "capping_count": 10,              // optional. The max number of emails that can be sent from a
                                        //           specific app to a particular device within a 'capping_days'
                                        //           period. In case the message created exceeds the
                                        //           'capping_count' limit for a device, it won't
                                        //           be sent to that device.
      "capping_exclude": true,          // optional. If set to true, this email will not
                                        //           be counted towards the capping for future emails.
      "capping_avoid": true,            // optional. If set to true, capping will not be applied to
                                        //           this specific email.
      "send_rate": 100,                 // optional. Throttling limit.
                                        //           Limit how many messages can be sent per second across all users.
                                        //           Helps prevent backend overload during high-volume sends.
      "send_rate_avoid": true,          // optional. If set to true, throttling limit will not be applied to
                                        //           this specific email.
    }]
  }
}

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

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

200

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

210

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

400

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

403

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

500

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

مثال

{
  "request": {
    "application": "APPLICATION_CODE",   // required. Pushwoosh application code.
    "email":"email@domain.com",          // required. Email address to be registered.
    "language": "en",                    // optional. Language locale.
    "userId": "userId",                  // optional. User ID to associate with the email address.
    "tz_offset": 3600,                   // optional. Timezone offset in seconds.
    "tags": {                            // optional. Tag values to set for the device registered.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
       "DateTag": "2024-10-02 22:11",    // note the time should be in UTC
       "BooleanTag": true                // valid values are: true, false
    }
  }
}

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

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

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

نصيحة

أعد محاولة استجابات 500 فقط، باستخدام التراجع الأسي — إنها الحالة العابرة الوحيدة. 210 أو 400 أو 403 نهائي: فهم الخادم طلبك ورفضه، لذا فإن تكراره دون تغيير يعيد نفس النتيجة. سجل العنوان (لـ 210) أو أصلح الطلب/الرمز (لـ 400/403) بدلاً من ذلك.

رسائل الخطأ 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	الحساب على خطة بريد إلكتروني فقط ولا يمكنه تسجيل أجهزة غير بريد إلكتروني.

ملاحظة

فقط الارتدادات الدائمة (الصعبة) تضيف عنوانًا إلى القائمة السوداء. الارتدادات الناعمة وشكاوى البريد العشوائي لا تمنع registerEmail — فقط this hwid (email) is blacklisted يعكس الحظر.

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",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}

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) المرتبط بعنوان البريد الإلكتروني.

200

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

مثال

{
  "request": {
    "email": "email@domain.com",                  // required. Email address to set tags for.
    "application": "APPLICATION_CODE",            // required. Pushwoosh application code.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // time in UTC
      "BooleanTag": true                          // valid values are: true, false
    },
    "userId": "userId"                            // optional. User ID associated with the email address.
  }
}

ملاحظة

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

تنبيه

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

registerEmailUser

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

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	معرف المستخدم (User ID) لربطه بعنوان البريد الإلكتروني.
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", // required. Pushwoosh application code.
    "email": "email@domain.com",       // required. User email address.
    "userId": "userId",                // required. User ID to associate with the email address.
    "tz_offset": 3600                  // optional. Timezone offset in seconds.
  }
}

ملاحظة

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